# Introduction
Source: https://docs.dialect.to/alerts/alerts-and-monitoring/index

Before you can send programmatic alerts to your users, you need to detect when events worth notifying about actually happen. This section covers different strategies for monitoring and detecting events in your application.

## Getting Started

1. **[Register Your App](/alerts/setup/register-app)** - Set up your application in Dialect
2. **[Choose your monitoring approach](#choose-your-path)** - Pick the path that fits your current setup
3. **[Send Alerts](/alerts/send)** - Learn how to send notifications using our API, SDK, or Dashboard

## Choose Your Path

### I Need Event Detection

You don't have event monitoring in place yet and need a complete solution. Dialect provides open-source monitoring tooling (Dialect Monitor) that can detect on-chain and off-chain events automatically. This is ideal when you want a ready-made solution for common blockchain events.

**Best for:** On-chain events, DeFi protocols, NFT marketplaces, standard blockchain monitoring needs, teams without existing monitoring infrastructure.

[Learn how to set up Dialect Monitor →](/alerts/alerts-and-monitoring/setup-event-detection)

### I Have Event Detection

You already have event detection systems in your backend (webhooks, database triggers, custom monitoring, existing alerting systems) and want to integrate Dialect's alert sending directly into your existing workflows using our SDK or API.

**Best for:** Custom business logic, existing backend systems, complex event patterns, off-chain events, teams with established monitoring infrastructure.

[Learn how to integrate with existing systems →](/alerts/alerts-and-monitoring/integrate-existing-system)

## What You'll Find Here

* **[Setup Event Detection](/alerts/alerts-and-monitoring/setup-event-detection)** - Complete guide to our monitoring tooling
* **[Integrate Existing System](/alerts/alerts-and-monitoring/integrate-existing-system)** - Integrate with your backend
* Implementation guides and examples


# Integrate with Existing Systems
Source: https://docs.dialect.to/alerts/alerts-and-monitoring/integrate-existing-system

Integrate Dialect's alert sending directly into your existing workflows and event detection systems

If you already have event detection in your backend (webhooks, database triggers, custom monitoring, existing alerting systems), you can integrate Dialect's alert sending directly into your existing workflows. This approach leverages your current infrastructure while adding Dialect's multi-channel notification capabilities.

<Info>
  **When to Use This Approach**

  * ✅ You have existing event detection systems
  * ✅ You have custom business logic for notifications
  * ✅ You prefer to control when and how events are detected
  * ✅ Your events are primarily off-chain or custom patterns
  * ✅ You want to integrate with existing backend services

  **Alternative:** If you need event detection, check out [Dialect Monitor](/alerts/alerts-and-monitoring/setup-event-detection) for automated monitoring solutions.
</Info>

## Integration Overview

The integration process involves two main steps:

1. **Configure Dialect SDK/API** in your backend services
2. **Send notifications** at the point of events in your application

```mermaid theme={null}
flowchart LR
    A["Your Backend<br/>Event"] --> B["Event<br/>Handler"] --> C["Dialect<br/>SDK/API"] --> D["Multi-Channel<br/>Delivery"] --> E["User<br/>Devices"]
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:3px
    style B fill:#e3f2fd,stroke:#1976d2,stroke-width:3px
    style C fill:#e3f2fd,stroke:#1976d2,stroke-width:3px
    style D fill:#e3f2fd,stroke:#1976d2,stroke-width:3px
    style E fill:#e3f2fd,stroke:#1976d2,stroke-width:3px
```

## Choose Your Integration Method

### Option 1: TypeScript SDK (Recommended)

Best for Node.js/TypeScript backends. Provides type safety and simplified API.

**Setup & Configuration:**

Follow our complete [SDK Setup & Configuration guide](/alerts/send/sdk/setup-configuration) for installation, app registration, and initialization.

**Send Messages:**

Use our [SDK Send Messages guide](/alerts/send/sdk/send-messages) for comprehensive examples including:

* Single user notifications
* Batch notifications to multiple users
* Channel-specific delivery (email, Telegram, push)
* Interactive notifications with action buttons
* Rich content and formatting

### Option 2: REST API

Best for non-JavaScript backends or custom integrations.

**Setup & Configuration:**

Follow our complete [API Authentication guide](/alerts/send/api/authentication) for API key setup and request authentication.

**Send Messages:**

Use our [API Send Messages guide](/alerts/send/api/send-messages) for comprehensive examples including:

* Individual and batch messaging
* Channel targeting
* Rich HTML content for emails
* Interactive notifications with actions

## Real-World Integration Examples

**[Realms Governance API](https://github.com/dialectlabs/governance-api)**

* **Use case**: Powers notifications for post and comment upvotes and replies on [Realms Discover](https://app.realms.today/discover)
* **Implementation**: Direct backend integration using Dialect SDK within NestJS architecture
* **Features**: Event-driven notifications from existing services, custom business logic integration

**[Realms Monitoring Service](https://github.com/dialectlabs/realms-monitoring-service)**

* **Use case**: DAO proposal and governance event monitoring
* **Implementation**: Dialect Monitor integration for automated event detection
* **Features**: Proposal tracking, voting reminders, and governance event notifications

**[Jet Protocol](https://github.com/dialectlabs/jet-monitoring-service)**

* **Use case**: Liquidation warnings for DeFi lending positions
* **Implementation**: Monitoring service with backend integration patterns
* **Features**: Threshold-based notifications and risk management alerts

**[Marinade Finance](https://github.com/dialectlabs/marinade-monitoring-service)**

* **Use case**: Staking protocol notifications and updates
* **Implementation**: Backend integration with broadcast messaging features
* **Features**: Multi-user notifications and staking event detection

**[Saber](https://github.com/dialectlabs/saber-monitoring-service)**

* **Use case**: Trading and AMM protocol notifications
* **Implementation**: Push-type data sources with multi-channel delivery
* **Features**: Real-time trading alerts and cross-platform integration

**[Investin](https://github.com/dialectlabs/investin-monitoring-service)**

* **Use case**: Investment platform with multiple notification types
* **Implementation**: Complex backend with various notification triggers
* **Features**: Portfolio alerts, investment opportunities, and user engagement


# Setup Monitoring
Source: https://docs.dialect.to/alerts/alerts-and-monitoring/setup-event-detection

Use Dialect's open-source monitor library to detect events and turn them into targeted notifications with sophisticated data-stream processing

The monitor library is an open-source TypeScript package that makes it easy to extract and transform data streams into targeted, timely smart messages with a rich, high-level API for unbounded data-stream processing.

## Key Features

Data-stream processing features include:

* **Windowing** - fixed size, fixed time, fixed size sliding
* **Aggregation** - average, min, max
* **Thresholding** - rising edge, falling edge
* **Rate limiting**

## Getting Started

### Prerequisites

Before building your monitor, you'll need:

1. A Dialect SDK instance configured with your dApp's wallet
2. A defined data type that represents what you want to monitor

### Basic Setup

```typescript theme={null}
import { Monitor, Monitors, Pipelines, ResourceId, SourceData } from "@dialectlabs/monitor";
import { Duration } from "luxon";
import { Dialect, DialectCloudEnvironment, DialectSdk } from "@dialectlabs/sdk";
import {
  Solana,
  SolanaSdkFactory,
  NodeDialectSolanaWalletAdapter,
} from "@dialectlabs/blockchain-sdk-solana";

// 1. Create Dialect SDK
const environment: DialectCloudEnvironment = "development";
const dialectSolanaSdk: DialectSdk<Solana> = Dialect.sdk(
  {
    environment,
  },
  SolanaSdkFactory.create({
    // IMPORTANT: Set DIALECT_SDK_CREDENTIALS environment variable
    // to your dapp's Solana messaging wallet keypair e.g. [170,23, . . . ,300]
    wallet: NodeDialectSolanaWalletAdapter.create(),
  })
);

// 2. Define your data type
type YourDataType = {
  cratio: number;
  healthRatio: number;
  resourceId: ResourceId;
};
```

## Building Your Monitor

### 1. Initialize the Monitor Builder

```typescript theme={null}
const monitor: Monitor<YourDataType> = Monitors.builder({
  sdk: dialectSolanaSdk,
  subscribersCacheTTL: Duration.fromObject({ seconds: 5 }),
})
  .defineDataSource<YourDataType>()
```

### 2. Supply Data (Poll or Push)

<Tabs>
  <Tab title="Polling Data Source">
    Use this when you want to regularly check for data changes:

    ```typescript theme={null}
      .poll((subscribers: ResourceId[]) => {
        const sourceData: SourceData<YourDataType>[] = subscribers.map(
          (resourceId) => ({
            data: {
              cratio: Math.random(), // Replace with your actual data collection
              healthRatio: Math.random(),
              resourceId,
            },
            groupingKey: resourceId.toString(),
          })
        );
        return Promise.resolve(sourceData);
      }, Duration.fromObject({ seconds: 3 })) // Poll every 3 seconds
    ```
  </Tab>

  <Tab title="Push Data Source">
    Use this when you have event-driven data (webhooks, database triggers, etc.). See the [push example](https://github.com/dialectlabs/monitor/blob/main/examples/007-pushy-data-source-monitor.ts) for implementation details.
  </Tab>
</Tabs>

### 3. Transform Data to Detect Events

During the transform step, streaming data is processed to identify events that should trigger notifications:

```typescript theme={null}
  .transform<number, number>({
    keys: ['cratio'], // Which data fields to monitor
    pipelines: [
      Pipelines.threshold({
        type: 'falling-edge', // Trigger when value drops below threshold
        threshold: 0.5,
      }),
    ],
  })
```

#### Available Transformations

* **Thresholding**: `rising-edge`, `falling-edge`
* **Windowing**: Fixed size, fixed time, sliding windows
* **Aggregation**: Average, min, max operations
* **Array Diff**: Track additions/removals from arrays

For more examples, see:

* [Custom Pipeline Operators](https://github.com/dialectlabs/monitor/blob/main/examples/005-custom-pipelines-using-operators.ts)
* [Array Diff Pipeline](https://github.com/dialectlabs/monitor/blob/main/examples/008-diff-pipeline.ts)

### 4. Add Notification Logic

The notify step defines how to send alerts when events are detected:

```typescript theme={null}
  .notify()
  .dialectSdk(
    ({ value }) => {
      return {
        title: "dApp cratio warning",
        message: `Your cratio = ${value} below warning threshold`,
      };
    },
    {
      dispatch: "unicast", // unicast, multicast, or broadcast
      to: ({ origin: { resourceId } }) => resourceId,
    }
  )
```

#### Dispatch Types

* **unicast**: Send to one specific subscriber
* **multicast**: Send to multiple specific subscribers
* **broadcast**: Send to all subscribers

You can also create [custom notification sinks](https://github.com/dialectlabs/monitor/blob/main/examples/004-custom-notification-sink.ts) for specialized delivery methods.

### 5. Build and Start the Monitor

```typescript theme={null}
  .and()
  .build();

// Start monitoring
monitor.start();
```

## Complete Example

Here's a full working example that monitors collateralization ratios and sends warnings:

```typescript theme={null}
const dataSourceMonitor: Monitor<YourDataType> = Monitors.builder({
  sdk: dialectSolanaSdk,
  subscribersCacheTTL: Duration.fromObject({ seconds: 5 }),
})
  .defineDataSource<YourDataType>()
  .poll((subscribers: ResourceId[]) => {
    const sourceData: SourceData<YourDataType>[] = subscribers.map(
      (resourceId) => ({
        data: {
          cratio: Math.random(),
          healthRatio: Math.random(),
          resourceId,
        },
        groupingKey: resourceId.toString(),
      })
    );
    return Promise.resolve(sourceData);
  }, Duration.fromObject({ seconds: 3 }))
  
  // Warning when cratio drops below 0.5
  .transform<number, number>({
    keys: ["cratio"],
    pipelines: [
      Pipelines.threshold({
        type: "falling-edge",
        threshold: 0.5,
      }),
    ],
  })
  .notify()
  .dialectSdk(
    ({ value }) => {
      return {
        title: "dApp cratio warning",
        message: `Your cratio = ${value} below warning threshold`,
      };
    },
    {
      dispatch: "unicast",
      to: ({ origin: { resourceId } }) => resourceId,
    }
  )
  
  // Recovery notification when cratio rises above 0.5
  .also()
  .transform<number, number>({
    keys: ["cratio"],
    pipelines: [
      Pipelines.threshold({
        type: "rising-edge",
        threshold: 0.5,
      }),
    ],
  })
  .notify()
  .dialectSdk(
    ({ value }) => {
      return {
        title: "dApp cratio recovered",
        message: `Your cratio = ${value} is now above warning threshold`,
      };
    },
    {
      dispatch: "unicast",
      to: ({ origin: { resourceId } }) => resourceId,
    }
  )
  .and()
  .build();

dataSourceMonitor.start();
```

## Testing Your Monitor

### Step 1: Generate Test Keypair

```bash theme={null}
export your_path=~/projects/dialect/keypairs/
solana-keygen new --outfile ${your_path}/monitor-localnet-keypair.private
solana-keygen pubkey ${your_path}/monitor-localnet-keypair.private > ${your_path}/monitor-localnet-keypair.public
```

### Step 2: Start Server

```bash theme={null}
cd examples
export your_path=~/projects/dialect/keypairs
DIALECT_SDK_CREDENTIALS=$(cat ${your_path}/monitor-localnet-keypair.private) ts-node ./your-monitor.ts
```

### Step 3: Test with Client

```bash theme={null}
cd examples
export your_path=~/projects/dialect/keypairs
DAPP_PUBLIC_KEY=$(cat ${your_path}/monitor-localnet-keypair.public) \
ts-node ./your-client.ts
```

## Hosting Your Monitor

<Tabs>
  <Tab title="Your Infrastructure">
    If you already have a preferred hosting framework, you can simply deploy your monitor there and skip to setting up your [notification UI/UX](/alerts/integrate-inbox/).
  </Tab>

  <Tab title="Dialect Monitoring Service">
    Dialect offers an opinionized, standardized way of hosting monitors within a Nest.js server implementation.

    **Reference Implementation:**

    * [Monitoring Service Template](https://github.com/dialectlabs/monitoring-service-template)
  </Tab>
</Tabs>

### Real-World Examples

Explore these open-source implementations for inspiration:

#### Governance / DAO

* **[Realms](https://github.com/dialectlabs/realms-monitoring-service.git)** - Complex DAO and proposal monitoring

#### DeFi Protocols

* **[Jet](https://github.com/dialectlabs/jet-monitoring-service.git)** - Liquidation warnings with thresholding
* **[Marinade](https://github.com/dialectlabs/marinade-monitoring-service)** - Notification types and broadcast features
* **[Saber](https://github.com/dialectlabs/saber-monitoring-service.git)** - Push-type data sources and Twitter integration
* **[Investin](https://github.com/dialectlabs/investin-monitoring-service)** - Multiple monitor builders for different use cases

<Info>
  These examples may not use the latest Dialect packages. Use them for learning, but implement your monitor with the latest dependencies for new features and bug fixes.
</Info>

## Advanced Features

### Multiple Transforms

You can chain multiple transformations using `.also()`:

```typescript theme={null}
.transform(/* first transformation */)
.notify(/* first notification */)
.also()
.transform(/* second transformation */)
.notify(/* second notification */)
```

### Custom Pipelines

Create custom pipeline operators for specialized data processing needs. See the [custom pipelines example](https://github.com/dialectlabs/monitor/blob/main/examples/005-custom-pipelines-using-operators.ts).

### Rate Limiting

Built-in rate limiting prevents notification spam while ensuring important alerts get through.

## Next Steps

Once your monitor is built and hosted:

1. **[Set up notification UI/UX](/alerts/integrate-inbox)** - Create user interfaces for subscription management
2. **[Configure topics and channels](/alerts/setup/topics-channels-subscribers)** - Organize your notifications
3. **[Send additional alerts](/alerts/send)** - Combine monitoring with manual alert sending

## Contributing

We welcome contributions to the Monitor library! Check out the [GitHub repository](https://github.com/dialectlabs/monitor) to add custom features for your specific use cases.


# Request API Keys
Source: https://docs.dialect.to/alerts/api-keys

Get your API keys for Dialect Alerts and start sending notifications to your users in minutes.

<img alt="Request API Keys for Alerts" />

## How it works

API keys for Alerts are created automatically when you register your app in the Dialect Dashboard. To do so please follow the steps below:

<Steps>
  <Step title="Navigate to the Dashboard">
    Head to the [Dialect Dashboard](https://dashboard.dialect.to/) and connect
    your wallet.

    NOTE: If you're having trouble connecting your wallet, try using a VPN and refreshing the page. This is especially common in the UAE.
  </Step>

  <Step title="Register your app">
    Click on "Register your Project" and fill out the required fields. [Learn more](/alerts/setup/register-app).
  </Step>

  <Step title="Get your API keys">
    Once registered, they're available in the [API Keys](https://dashboard.dialect.to/api-keys) section of the dashboard. You can't find the keys before registering your project.
  </Step>
</Steps>

For a full walkthrough, see the [Alerts Quick Start](/alerts/quick-start).

## Need Help?

If you have questions about API keys or need assistance, reach out to us at [hello@dialect.to](mailto:hello@dialect.to).


# Blinks in Alerts
Source: https://docs.dialect.to/alerts/blinks-in-alerts

Send actionable alerts with embedded Blinks and let your users complete onchain transactions directly in your app. No more redirects or app switching.

<img alt="Blinks in Alerts" />

When Dialect's mapping service detects supported protocol URLs in your alerts, it automatically enriches them with contextual data and blink URLs, allowing your users to take immediate action.

<CardGroup>
  <Card title="In-app interactions" icon="mobile">
    Users never leave your application
  </Card>

  <Card title="Contextual data" icon="database">
    Rich information to build informed UIs
  </Card>

  <Card title="Reduced complexity" icon="wrench">
    Blinks handle protocol integrations
  </Card>

  <Card title="Faster user action" icon="bolt">
    Complete transactions in seconds
  </Card>
</CardGroup>

<Note>
  Currently supports lending protocols (Jupiter Borrow), with more protocols and use cases coming soon.
</Note>

## Example: Liquidation Warning Flow

For this example, we'll use Jupiter Borrow as the protocol and a scenario where a user's lending position reaches a critical LTV threshold.

### Scenario

* User has a SOL/USDC lending position on Jupiter Borrow
* Position reaches 78% LTV (liquidation threshold is 80%)
* User receives a liquidation warning alert

### Step 1: Send the Alert

Your backend sends an alert with the protocol website URL:

```json {13} theme={null}
{
  "recipient": {
    "type": "subscriber",
    "walletAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176"
  },
  "channels": ["IN_APP", "PUSH"],
  "message": {
    "title": "Liquidation Warning",
    "body": "Your SOL/USDC position is at 78% LTV, approaching liquidation threshold of 80%.",
    "actions": [{
      "type": "link",
      "label": "Add Collateral",
      "url": "https://jup.ag/lend/borrow/1/nfts/2433"
    }]
  }
}
```

### Step 2: Client Receives Enriched Alert

Dialect detects the Jupiter Borrow URL and enriches the response:

```json {10-14} theme={null}
{
  "id": "alert-uuid",
  "title": "Liquidation Warning",
  "body": "Your SOL/USDC position is at 78% LTV, approaching liquidation threshold of 80%.",
  "timestamp": "2024-01-15T10:30:00Z",
  "actions": [{
    "type": "link",
    "label": "Add Collateral",
    "url": "https://jup.ag/lend/borrow/1/nfts/2433",
    "context": {
      "type": "position",
      "apiUrl": "https://markets.dial.to/api/v0/positions/owners?walletAddresses=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176&bundleIds=jupiter.borrow.1.2433",
      "action": "deposit"
    }
  }]
}
```

### Step 3: Fetch Position Data

When the user clicks a button in the alert, fetch the position data from the [Markets and Positions API](/api-reference/positions/list-all-market-positions-by-wallet-address):

```bash theme={null}
curl 'https://markets.dial.to/api/v0/positions/owners?walletAddresses=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176&bundleIds=jupiter.borrow.1.2433' \
  --header 'x-dialect-api-key: pk_demo'
```

The response includes detailed position and market data:

```json theme={null}
{
  "positions": [
    {
      "id": "jupiter.borrow.1.2433.deposit",
      "type": "lending",
      "marketId": "jupiter.borrow.1",
      "ownerAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
      "bundleId": "jupiter.borrow.1.2433",
      "side": "deposit",
      "additionalData": {
        "vaultId": 1,
        "nftId": 2433
      },
      "actions": {
        "deposit": {
          "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/deposit?positionId=2433"
        },
        "withdraw": {
          "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/2433/withdraw"
        }
      },
      "amount": 0.015060007,
      "amountUsd": 3.34,
      "ltv": 0.3033,
      "liquidationPrice": 84.00917409932147,
      "market": { ... }
    },
    // ... borrow position
  ]
}
```

<Accordion title="View complete API response with all fields">
  ```json theme={null}
  {
    "positions": [
      {
        "id": "jupiter.borrow.1.2433.deposit",
        "type": "lending",
        "marketId": "jupiter.borrow.1",
        "ownerAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
        "bundleId": "jupiter.borrow.1.2433",
        "side": "deposit",
        "additionalData": {
          "vaultId": 1,
          "nftId": 2433
        },
        "actions": {
          "deposit": {
            "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/deposit?positionId=2433"
          },
          "withdraw": {
            "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/2433/withdraw"
          }
        },
        "amount": 0.015060007,
        "amountUsd": 3.34,
        "ltv": 0.3033,
        "liquidationPrice": 84.00917409932147,
        "market": {
          "id": "jupiter.borrow.1",
          "type": "lending",
          "provider": {
            "id": "jupiter",
            "name": "Jupiter",
            "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/5c23c065-89ef-413b-8deb-6d8c6a849300/public"
          },
          "token": {
            "address": "So11111111111111111111111111111111111111112",
            "symbol": "WSOL",
            "decimals": 9,
            "icon": "https://coin-images.coingecko.com/coins/images/21629/large/solana.jpg?1696520989"
          },
          "borrowToken": {
            "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
            "symbol": "USDC",
            "decimals": 6,
            "icon": "https://coin-images.coingecko.com/coins/images/6319/large/usdc.png?1696506694"
          },
          "websiteUrl": "https://jup.ag/lend/borrow/1",
          "depositApy": 0.0784,
          "baseDepositApy": 0.0484,
          "borrowApy": 0.0597,
          "baseBorrowApy": 0.0597,
          "totalDeposit": 665220.958436127,
          "totalDepositUsd": 147340132.39,
          "totalBorrow": 80014008.8212,
          "totalBorrowUsd": 79990184.41,
          "maxBorrow": 120021000.673021,
          "maxLtv": 0.75,
          "liquidationLtv": 0.8,
          "liquidationPenalty": 0.01,
          "additionalData": {},
          "actions": {
            "deposit": {
              "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/deposit"
            }
          }
        }
      },
      {
        "id": "jupiter.borrow.1.2433.borrow",
        "type": "lending",
        "marketId": "jupiter.borrow.1",
        "ownerAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
        "bundleId": "jupiter.borrow.1.2433",
        "side": "borrow",
        "additionalData": {
          "vaultId": 1,
          "nftId": 2433
        },
        "actions": {
          "borrow": {
            "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/2433/borrow"
          },
          "repay": {
            "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/2433/repay"
          }
        },
        "amount": 1.012143,
        "amountUsd": 1.01,
        "ltv": 0.3033,
        "liquidationPrice": 84.00917409932147,
        "market": {
          "id": "jupiter.borrow.1",
          "type": "lending",
          "provider": {
            "id": "jupiter",
            "name": "Jupiter",
            "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/5c23c065-89ef-413b-8deb-6d8c6a849300/public"
          },
          "token": {
            "address": "So11111111111111111111111111111111111111112",
            "symbol": "WSOL",
            "decimals": 9,
            "icon": "https://coin-images.coingecko.com/coins/images/21629/large/solana.jpg?1696520989"
          },
          "borrowToken": {
            "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
            "symbol": "USDC",
            "decimals": 6,
            "icon": "https://coin-images.coingecko.com/coins/images/6319/large/usdc.png?1696506694"
          },
          "websiteUrl": "https://jup.ag/lend/borrow/1",
          "depositApy": 0.0784,
          "baseDepositApy": 0.0484,
          "borrowApy": 0.0597,
          "baseBorrowApy": 0.0597,
          "totalDeposit": 665220.958436127,
          "totalDepositUsd": 147340132.39,
          "totalBorrow": 80014008.8212,
          "totalBorrowUsd": 79990184.41,
          "maxBorrow": 120021000.673021,
          "maxLtv": 0.75,
          "liquidationLtv": 0.8,
          "liquidationPenalty": 0.01,
          "additionalData": {},
          "actions": {
            "deposit": {
              "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/deposit"
            }
          }
        }
      }
    ]
  }
  ```
</Accordion>

### Step 4: Build the UI

With the response data, you can build rich UIs ranging from simple action buttons in your notification feed to full detail screens with position cards, input interfaces, and transaction controls. The response includes all the data you need: protocol information, token details, position health metrics, blink URLs for actions, and more.

<img alt="Full deposit screen example showing position details and deposit interface" />

For more details on available data fields, and ideas on how to use the data, see [using the data](/alerts/integrate-inbox/api/notifications#using-the-data).

### Step 5: Execute Transaction

When the user submits:

1. Call the blink URL with user's wallet address and amount
2. Receive ready-to-sign transaction
3. Prompt user to sign with their wallet
4. Submit transaction to blockchain
5. Show success state and updated position metrics

## Key Concepts

### Mapping Service

Dialect's mapping service automatically detects supported protocol URLs in your alerts and enriches them with actionable context. Here's the flow:

<Steps>
  <Step title="URL Detection">
    Your app sends an alert with a protocol URL (e.g., `https://jup.ag/lend/borrow/1/nfts/2433`). The mapping service recognizes the URL pattern from supported protocols.
  </Step>

  <Step title="Context Enrichment">
    The service extracts position identifiers from the URL (vault ID, position ID, wallet address) and adds a `context` object to the notification action containing:

    * `type`: The kind of data available (e.g., `"position"`)
    * `apiUrl`: A pre-filled API endpoint to fetch detailed data
    * `action`: The suggested action for the user (e.g., `"deposit"`)
  </Step>

  <Step title="Client Receives Enhanced Alert">
    Your client receives the original alert plus the enriched context. The context object is **only present** when the URL is recognized. The original protocol URL remains available as a fallback.
  </Step>
</Steps>

This approach allows you to send simple alerts with protocol URLs, and Dialect automatically adds the necessary context for building rich, actionable UIs.

### Context Object

The `context` object provides everything your client needs to fetch additional data and build interactive experiences:

```typescript theme={null}
{
  type: string,               // Type of context data available
  apiUrl: string,             // Pre-filled API endpoint
  action: string              // Suggested action type
}
```

**Fields:**

* **`type`**: Determines what kind of data the `apiUrl` will return. Currently `"position"` for lending/borrowing positions. Additional types will be added in the future.
* **`apiUrl`**: Complete API endpoint with all required parameters already filled in. Call this URL to get detailed position, market, and blink data.
* **`action`**: The recommended action for the user based on the alert context (e.g., `"deposit"`)

The `type` field is important because it tells your client how to interpret and display the data from the API response.

## Implementation

<CardGroup>
  <Card title="Sending Alerts with Blinks" icon="paper-plane" href="/alerts/send/api/send-messages#actionable-notifications">
    Learn how to send alerts with blinks.
  </Card>

  <Card title="Blinks in your inbox" icon="inbox" href="/alerts/integrate-inbox/api/notifications#working-with-blink-actions">
    Handle blinks on the client side.
  </Card>
</CardGroup>


# Introduction to Events
Source: https://docs.dialect.to/alerts/events/index

Integrate onchain and other market events into your products, as webhooks or bundled with Dialect's Alerts Stack.

<Note>
  **Beta Access Required**

  Events is currently in beta. To request early access, please contact our team at [hello@dialect.to](mailto:hello@dialect.to).
</Note>

<img alt="Dialect Events System" />

# Overview

Dialect's Events system provides real-time detection and delivery of blockchain-specific events. These events can be used standalone via webhook delivery, or bundled with Dialect's Alerts Stack as off-the-shelf topics.

Developers of all types can use Events for different purposes: to deliver timely alerts to their users, power other custom wallet app event-based capabilities, or even to power trading tools. No complex monitoring infrastructure required.

## What are Events?

Events are triggered when specific onchain or market conditions are met, such as an interesting price change for a token held in a wallet, or a new token is trending.

When an event is detected, the Events system executes the configured behavior: either a webhook delivery or an Alerts Stack notification.

## Use Cases

<CardGroup>
  <Card title="Mobile Wallets" icon="mobile">
    Notify users about significant price movements in their portfolio
  </Card>

  <Card title="Trading Platforms" icon="chart-line">
    Alert traders to breakthrough tokens and market opportunities
  </Card>

  <Card title="Portfolio Trackers" icon="wallet">
    Provide timely updates on token performance
  </Card>

  <Card title="DeFi Applications" icon="coins">
    Trigger actions based on market conditions
  </Card>
</CardGroup>

## Supported Event Types

Dialect supports two event types:

1. Price Change Events (Market-Based and Trade-Based)
2. Trending Token Events

### Price Change Events

Price change events detect significant price movements in tokens through two approaches:

* **Market-Based**: Track price movements over sliding time windows (e.g., "SOL is up 10% in 24h")
* **Trade-Based**: Personalized alerts relative to users' actual trade prices (e.g., "SOL is up 50% since you bought")

To read more about both types of price change events, see [Price Change Events](/alerts/events/price-change).

### Trending Token Events

Trending token events trigger when a newly-launched token graduates from a launchpad and meets strict performance criteria.

To read more about this event type, see [Trending Token Events](/alerts/events/trending-token).

## Detecting Interesting Events

Most interesting events are difficult to detect. Some events like "SOL is over \$150" may be easy to detect and can sometimes be useful. But it is much more interesting, and much harder, to detect that a token is undergoing unusual price movement, or that one trending token meets strict performance criteria among the many thousands of others that were launched on the same day.

It is also difficult to build an events system that is real time, capable of detecting optimally interesting events, and is rate limited.

Dialect's Events uses advanced techniques to satisfy all three of these across all of of our Event types. To read more about it, see [Technical Overview](/alerts/events/technical-overview).

## New event types

We are building more event types every month. Have one in mind? Get in touch with us.


# Price Change Events
Source: https://docs.dialect.to/alerts/events/price-change

Track token price movements with market-wide sliding windows or personalized alerts based on individual trading history. Get instant notifications when tokens hit thresholds, with smart filtering that cuts through market noise.

<Note>
  **Beta Access Required**

  Price Change Events are currently in beta. To request early access, please contact our team at [hello@dialect.to](mailto:hello@dialect.to).
</Note>

## Overview

Dialect offers two types of price change detection:

1. **Market-Based Price Changes**: Track price movements over sliding time windows (e.g., "SOL is up 10% in 24h")
2. **Trade-Based Price Changes**: Personalized alerts relative to users' actual trade prices (e.g., "SOL is up 50% since you bought")

Both systems use complex threshold detection and advanced filtering to deliver only the most relevant alerts.

## Market-Based Price Changes

Market-Based Price Changes are triggered by significant price movements of a token over sliding time windows using percentage change thresholds.

### How It Works

Dialect continuously monitors token prices and analyzes percentage changes over sliding time windows. When a token's price change exceeds the configured threshold within a time window, a webhook is triggered with detailed information about the price movement.

### Sliding Window Analysis

Price changes are calculated using a sliding window approach:

* **Window Duration**: Configurable time periods (1h, 3h, 6h, 12h, 24h, 7d)
* **Threshold**: Percentage change required to trigger an event
* **Direction**: Both upward and downward movements are detected

### Supported Time Windows

| Window | Beta Status   | Use Case                                    |
| ------ | ------------- | ------------------------------------------- |
| 1h     | Future        | Momentum detection, immediate market shifts |
| 3h     | **Available** | Short-term trend confirmation               |
| 6h     | **Available** | Intraday trend identification               |
| 12h    | **Available** | Half-day trend analysis                     |
| 24h    | **Available** | Daily price movement tracking               |
| 7d     | Planned       | Weekly trend detection                      |

### Market-Based Webhook Payload

```json theme={null}
{
  "events": [
    {
      "event": "token_price_change",
      "timestamp": "2025-07-04T14:30:00Z",
      "token": {
        "symbol": "SOL",
        "address": "So11111111111111111111111111111111111111112"
      },
      "trigger": {
        "type": "sliding_window_percentage_change",
        "window": {
          "duration": "24h"
        },
        "threshold": 10.0
      },
      "change": {
        "direction": "up",
        "from": {
          "timestamp": "2025-07-03T14:30:00Z",
          "value": 154.25
        },
        "to": {
          "timestamp": "2025-07-04T14:30:00Z",
          "value": 171.85
        },
        "absolute": 17.6,
        "percentage": 11.42
      }
    }
  ]
}
```

#### Market-Based Field Details

##### Event Metadata

* **event**: `token_price_change`
* **timestamp**: ISO 8601 UTC timestamp when event was generated

##### Token Information

* **symbol**: Token ticker symbol
* **address**: Token mint address on Solana

##### Trigger Details

* **type**: `sliding_window_percentage_change`
* **window**: Sliding window configuration
  * **duration**: Time window used for the calculation (e.g., `1h`, `3h`, `6h`, `12h`, `24h`, `7d`)
* **threshold**: The percentage change that must be crossed within the window to trigger the event

##### Change Information

* **direction**: `up` for price increases, `down` for decreases
* **from**: Price and timestamp at the start of the window
* **to**: Price and timestamp at the end of the window
* **absolute**: Raw price difference (`to.value - from.value`)
* **percentage**: Percentage change over the window (`(to.value - from.value) / from.value * 100`)

## Trade-Based Price Changes (Last Trade)

Trade-Based Price Changes are triggered by significant price movements of a token relative to a user's actual trading history. They offer a more personalized approach to [price change alerts](/alerts/events/price-change#market-based-price-changes), providing alerts based on a user's buy/sell behavior rather than market-wide price movements.

### How It Works

<Note>
  Please note that during the beta, we only support `buy` transactions that happened **after** the wallet was registered.
</Note>

1. **Registration**: Wallets must be explicitly registered to receive last trade events
2. **Trade Detection**: System monitors all swap transactions for the wallet
3. **Anchor Points**: Last buy price becomes the baseline for percentage calculations
4. **Threshold Monitoring**: Price changes are evaluated against market cap-specific thresholds
5. **Event Triggering**: Alerts fire when thresholds are crossed in either direction

### Registration Process

Wallets must be explicitly registered to receive last trade events. During beta:

* Contact us at [hello@dialect.to](mailto:hello@dialect.to) to register your wallets
* Projects provide wallet lists to Dialect for monitoring
* No backfill of historical trades (monitoring starts from registration)

### Trade-Based Threshold System

Thresholds are determined based on token market capitalization at the time of initial tracking:

#### Standard Position Thresholds

| Market Cap Range         | Uptrend Triggers             | Downtrend Triggers                     |
| ------------------------ | ---------------------------- | -------------------------------------- |
| **Large Cap** (>\$1B)    | +5%, +10%, then every +10%   | -5%, -10%, then every -10%             |
| **Mid Cap** ($50M-$500M) | +20%, +50%, then 2x, 3x, 4x… | -20%, -30%, then every -10% until -90% |
| **Small Cap** (\<\$50M)  | +50%, then 2x, 3x, 4x…       | -20%, -30%, then every -10% until -90% |
| **Micro Cap** (\<\$1M)   | +50%, 2x, then every 1x      | -30%, -50%, -70%, -90%                 |

#### Post-Exit Thresholds

After a full sell (100% position exit), different thresholds apply:

| Market Cap Range         | Uptrend Trigger | Downtrend Trigger |
| ------------------------ | --------------- | ----------------- |
| **Large Cap** (>\$1B)    | +30%            | -30%              |
| **Mid Cap** ($50M-$500M) | 2x              | -50%              |
| **Small Cap** (\<\$50M)  | 3x              | -50%              |
| **Micro Cap** (\<\$1M)   | 5x              | -70%              |

### Event Triggering Rules

#### Threshold Crossing

* Events trigger when price **fully crosses** a threshold
* Same threshold cannot trigger twice consecutively
* Price must cross another threshold before original can trigger again

#### Round Trip Detection

* System tracks when price returns to previous thresholds
* Generates contextual alerts like "TOKEN back to +50% from 2x"
* Helps users understand retracement patterns

#### Multiple Threshold Handling

* If multiple thresholds crossed in 5-minute window, only most significant triggers
* Prioritizes largest movement (highest for uptrend, lowest for downtrend)

### Trade-Based Webhook Payload

```json theme={null}
{
  "events": [
    {
      "event": "token_last_trade_price_change",
      "timestamp": "2025-09-17T16:03:10.259Z",
      "token": {
        "symbol": "TOKEN",
        "address": "TokenMintAddress..."
      },
      "walletAddress": "UserWalletAddress...",
      "trigger": {
        "type": "trade_percentage_change",
        "trade": {
          "type": "buy",
          "timestamp": "2024-01-15T10:00:00.000Z",
          "transactionId": "TxSignature...",
          "balance": {
            "before": 0,
            "after": 1000,
            "change": 1000
          }
        },
        "threshold": 50
      },
      "changes": {
        "triggerTrade": {
          "type": "trade_change",
          "trade": {
            "type": "buy",
            "timestamp": "2024-01-15T10:00:00.000Z",
            "transactionId": "TxSignature...",
            "balance": {
              "before": 0,
              "after": 1000,
              "change": 1000
            }
          },
          "change": {
            "direction": "up",
            "from": {
              "timestamp": "2024-01-15T10:00:00.000Z",
              "value": 1.00
            },
            "to": {
              "timestamp": "2025-09-17T16:03:10.259Z",
              "value": 1.50
            },
            "absolute": 0.50,
            "percentage": 50.0
          }
        },
        "lastTrade": {
          "type": "trade_change",
          "trade": {
            "type": "buy",
            "timestamp": "2024-01-15T10:00:00.000Z",
            "transactionId": "TxSignature...",
            "balance": {
              "before": 0,
              "after": 1000,
              "change": 1000
            }
          },
          "change": {
            "direction": "up",
            "from": {
              "timestamp": "2024-01-15T10:00:00.000Z",
              "value": 1.00
            },
            "to": {
              "timestamp": "2025-09-17T16:03:10.259Z",
              "value": 1.50
            },
            "absolute": 0.50,
            "percentage": 50.0
          }
        },
        "lastPeak": {
          "type": "peak_change",
          "change": {
            "direction": "down",
            "from": {
              "timestamp": "2025-09-17T12:00:00.000Z",
              "value": 2.00
            },
            "to": {
              "timestamp": "2025-09-17T16:03:10.259Z",
              "value": 1.50
            },
            "absolute": -0.50,
            "percentage": -25.0
          }
        }
      }
    }
  ]
}
```

#### Trade-Based Field Descriptions

##### Event Metadata

* **event**: `token_last_trade_price_change`
* **timestamp**: ISO 8601 UTC timestamp when event was generated
* **walletAddress**: The wallet being monitored for this event

##### Token Information

* **symbol**: Token ticker symbol
* **address**: Token mint address on Solana

##### Trigger Details

* **type**: `trade_percentage_change`
* **trade**: The anchor trade (last buy or sell) used for calculations
  * **type**: `buy` or `sell`
  * **timestamp**: When the trade occurred
  * **transactionId**: Blockchain transaction signature
  * **balance**: Token balance changes
    * **before**: Balance before trade
    * **after**: Balance after trade
    * **change**: Net change (positive for buys, negative for sells)
* **threshold**: The percentage threshold that was crossed

##### Change Information

* **triggerTrade**: Price change from the anchor trade
* **lastTrade**: Price change from most recent trade
* **lastPeak**: Price change from previous alert threshold (optional)
  * Each contains:
    * **direction**: `up` or `down`
    * **from/to**: Start and end prices with timestamps
    * **absolute**: USD price difference
    * **percentage**: Percentage change

### Edge Cases

#### Partial Sells

* Last buy price remains the anchor
* Partial sells don't reset calculation baseline
* Allows tracking performance of remaining position
* If a subsequent **buy** occurs after a partial sell, that new buy **immediately replaces** the anchor; thresholds reset from the new buy price
* When multiple trades happen within the same 5‑minute time window, `lastTrade` always refers to the **chronologically latest** trade

#### SOL Handling

* Trade‑based SOL price changes are **muted in MVP**
* SOL is treated as an investment vehicle rather than a tracked asset for trade‑based alerts
* **Market‑based SOL** price change alerts remain available and are unaffected

#### Multiple Buys (DCA)

* Only most recent buy price is used as anchor
* No averaging across multiple purchases
* We do **not** average across buys. Any new buy supersedes the prior anchor and restarts threshold tracking

## Implementation Examples

### Market-Based Price Change Handler

```javascript theme={null}
app.post('/webhook/price-events', (req, res) => {
  const event = req.body;

  // Send push notification to users holding this token
  sendPushNotification({
    title: `${event.token.symbol} ${event.change.direction === 'up' ? '📈' : '📉'} ${event.change.percentage.toFixed(1)}%`,
    body: `${event.token.symbol} moved ${event.change.percentage.toFixed(1)}% in the last ${event.trigger.window.duration}`,
    data: {
      tokenAddress: event.token.address,
      priceChange: event.change.percentage
    }
  });

  res.status(200).send('OK');
});
```

### Trade-Based Price Change Handler

```javascript theme={null}
app.post('/webhook/last-trade-events', async (req, res) => {
  const { events } = req.body;

  for (const event of events) {
    const { walletAddress, token, trigger, changes } = event;

    // Determine alert message based on context
    let message;
    if (trigger.trade.type === 'buy' && !changes.lastPeak) {
      // Simple price change from buy
      message = `${token.symbol} is ${changes.triggerTrade.change.direction} ` +
        `${Math.abs(changes.triggerTrade.change.percentage).toFixed(1)}% ` +
        `since you bought`;
    } else if (changes.lastPeak) {
      // Round trip from previous threshold
      message = `${token.symbol} is back to ` +
        `${changes.triggerTrade.change.percentage > 0 ? '+' : ''}` +
        `${Math.abs(changes.triggerTrade.change.percentage).toFixed(1)}% ` +
        `from ${changes.lastPeak.change.percentage > 0 ? '+' : ''}` +
        `${Math.abs(changes.lastPeak.change.percentage).toFixed(1)}%`;
    }

    // Send personalized notification
    await sendUserNotification(walletAddress, {
      title: `${token.symbol} Price Alert`,
      body: message,
      data: {
        tokenAddress: token.address,
        currentPrice: changes.triggerTrade.change.to.value
      }
    });
  }

  res.status(200).send('OK');
});
```


# Technical Overview
Source: https://docs.dialect.to/alerts/events/technical-overview

Integrate price alerts and automated trading triggers using webhook events. Build powerful applications by subscribing to real-time market events. Configure price thresholds and receive structured webhook payloads to trigger your application logic.

## Architecture

### Event Detection Pipeline

1. **Data Ingestion**: Real-time price feeds and on-chain data monitoring
2. **Event Processing**: Sliding window analysis and threshold detection
3. **Webhook Delivery**: Reliable delivery to your infrastructure

### Webhook Delivery

When an event is detected, Dialect sends an HTTP POST request to your configured webhook endpoint with a structured JSON payload.

## Webhook Payload Schema

All webhooks deliver events as arrays, allowing for batch delivery of multiple events in a single request. You can receive multiple events of the same type or mixed event types in one webhook call:

```json theme={null}
{
  "events": [
    {
      "event": "token_price_change",
      "timestamp": "2025-07-04T14:30:00Z",
      "token": {
        "symbol": "SOL",
        "address": "So11111111111111111111111111111111111111112"
      },
      "trigger": {
        "type": "sliding_window_percentage_change",
        "window": {
          "duration": "24h"
        },
        "threshold": 10.0
      },
      "change": {
        "direction": "up",
        "from": {
          "timestamp": "2025-07-03T14:30:00Z",
          "value": 154.25
        },
        "to": {
          "timestamp": "2025-07-04T14:30:00Z",
          "value": 171.85
        },
        "absolute": 17.6,
        "percentage": 11.42
      }
    },
    {
      "event": "trending_token",
      "timestamp": "2025-08-05T12:45:30Z",
      "token": {
        "symbol": "BOSS",
        "address": "GUy9Tu8YtvvHoL3DcXLJxXvEN8PqEus6mWQUEchcbonk"
      },
      "trigger": {
        "type": "launchpad_graduated"
      },
      "metrics": {
        "graduatedAt": "2025-08-05T12:31:03Z",
        "marketCap": 9866748.92,
        "liquidity": 850000,
        "holders": 20324,
        "price": 0.0106,
        "launchpad": "raydium",
        "mintAuthorityDisabled": true,
        "freezeAuthorityDisabled": true,
        "topHoldersPercentage": 15.2,
        "socialCount": 1,
        "priceChange1h": -2.1,
        "priceChange6h": 8.5,
        "priceChange24h": 12.3
      }
    }
    // ... more events
  ]
}
```

### Common Fields

All events share these common fields:

* **event**: Event type identifier (`token_price_change`, `trending_token`, or `token_last_trade_price_change`)
* **timestamp**: UTC timestamp when the event was generated (ISO 8601)
* **token**: Token information including symbol and mint address
* **trigger**: Configuration that caused the event to fire

The rest of the data structure is event-specific. For detailed field descriptions and specifications, see the individual event type pages for:

* [Price Change](/alerts/events/price-change),
* [Trending Token](/alerts/events/trending-token), and
* [Last Trade Price Change](/alerts/events/price-change#trade-based-price-changes-last-trade)


# Trending Token Events
Source: https://docs.dialect.to/alerts/events/trending-token

Trending Token events trigger when a newly-launched token graduates from a launchpad and meets strict performance criteria. Get notified of high-potential tokens with built-in audit filters and advanced analytics.

<Tip>
  Trending Token Events are currently in beta. Contact us at [hello@dialect.to](mailto:hello@dialect.to) for early access or to discuss specific requirements.
</Tip>

## Webhooks

Webhooks for trending tokens can be delivered to power custom behavior in your infrastructure and apps. Reach out to the Dialect team for early access using the form above.

### Webhook Payload

When trending token events are detected, you'll receive a webhook with an array structure. Each individual event within the array has this structure:

```json theme={null}
{
  "events": [
    {
      "event": "trending_token",
      "timestamp": "2025-08-05T12:45:30Z",
      "token": {
        "symbol": "BOSS",
        "address": "GUy9Tu8YtvvHoL3DcXLJxXvEN8PqEus6mWQUEchcbonk"
      },
      "trigger": {
        "type": "launchpad_graduated"
      },
      "metrics": {
        "graduatedAt": "2025-08-05T12:31:03Z",
        "marketCap": 9866748.92,
        "liquidity": 850000,
        "holders": 20324,
        "price": 0.0106,
        "launchpad": "raydium",
        "mintAuthorityDisabled": true,
        "freezeAuthorityDisabled": true,
        "topHoldersPercentage": 15.2,
        "socialCount": 1,
        "priceChange1h": -2.1,
        "priceChange6h": 8.5,
        "priceChange24h": 12.3
      }
    }
  ]
}
```

#### Field Details

**Event Information**

* **event**: Always `"trending_token"` for trending token events
* **timestamp**: ISO 8601 timestamp when the event was detected

**Token Details**

* **symbol**: Token symbol (e.g., "BOSS")
* **address**: Solana token mint address

**Trigger Information**

* **type**: Always `"launchpad_graduated"` indicating token graduated from launchpad

**Token Metrics**

* **graduatedAt**: ISO 8601 timestamp when token graduated from launchpad
* **marketCap**: Current market capitalization in USD
* **liquidity**: Current liquidity pool value in USD
* **holders**: Number of unique token holders
* **price**: Current token price in USD
* **launchpad**: Name of the launchpad platform (e.g., "raydium, pump\_fun, etc.")
* **mintAuthorityDisabled**: `true` if mint authority revoked, `false` otherwise
* **freezeAuthorityDisabled**: `true` if freeze authority revoked, `false` otherwise
* **topHoldersPercentage**: Percentage of total supply held by top 10 holders
* **socialCount**: Number of verified social media accounts
* **priceChange1h**: Price change percentage over 1 hour window
* **priceChange6h**: Price change percentage over 6 hour window
* **priceChange24h**: Price change percentage over 24 hour window

## Data Sources

### Supported launchpads

New token events support the 40+ launchpads available on [Jupiter Pro](https://jup.ag/pro?tab=launchpads), including:

* pump.fun
* Letsbonk.fun
* BAGS
* Jupiter Studio
* & 40 more

## Detection Criteria

A variety of criteria must be met for an event to trigger, including familiar community "audit" filters, as well as additional analyses we have developed in-house to set a higher bar. Hundreds of tokens satisfy the audit criteria every day. Our added analysis sets a higher bar to just two to five daily.

### Community Audit Filters

All events must meet the familiar community "audit" filters:

* **✅ Mint Authority**: Revoked to prevent unlimited token creation.
* **✅ Freeze Authority**: Revoked to prevent account freezing.
* **✅ LP Burned**: Liquidity provider tokens burned for permanent liquidity.
* **✅ Holder Distribution**: Top 10 holders hold less than 20% of the total supply.
* **✅ Social Presence**: At least one verified social media account.

*Note: "Audit" refers to community trading terminology, not formal security audits.*

### Advanced Criteria

We employ an additional set of more advanced, in-house criteria to further filter the number of new token events per day. These include:

* **✅ Market cap**
* **✅ Liquidity**
* **✅ Price change**
* **✅ Trading volume change**

If you'd like to better understand what criteria we have in place, please reach out.

### Top-Down Tuning

Using the criteria above, we then apply a "top-down" tuning approach to achieve an ideal number of events per day, in this case two to five.


# Using Events
Source: https://docs.dialect.to/alerts/events/using-events

Learn how to use events to build powerful applications with real-time price alerts and trending token detection. Integrate webhooks, handle events, and deliver timely notifications to your users.

## Quick Start

### 1. Configure Webhook Endpoint

Set up an endpoint to receive event webhooks:

```javascript theme={null}
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/events', (req, res) => {
  const event = req.body;
  
  console.log('Received event:', event.event);
  console.log('Token:', event.token.symbol);
  
  // Process the event
  handleEvent(event);
  
  // Always respond with 200 OK
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});
```

### 2. Registration

#### 2.1 Register Your Webhook (required)

Contact us at [hello@dialect.to](mailto:hello@dialect.to) to register your webhook endpoint.

### 2.2 Register Users Wallets (only for last trade price change events)

If you want to offer last trade price change events to your users, you need to register their wallets. This can be done by submitting a list of wallet addresses to us. Please contact us at [hello@dialect.to](mailto:hello@dialect.to) before sending any materials.

### 3. Handle Events

Implement event handlers based on the event type:

```javascript theme={null}
function handleEvent(event) {
  switch (event.event) {
    case 'token_price_change':
      handlePriceChangeEvent(event);
      break;
    case 'token_last_trade_price_change':
      handleLastTradePriceChangeEvent(event);
      break;
    default:
      console.log('Unknown event type:', event.event);
  }
}
```

## Price Change Events

There are two types of price change events. Please remember to [send a list](/alerts/events/using-events#2-2-register-users-wallets-only-for-last-trade-price-change-events) with users wallets to us if you want to offer last trade price change events to your users.

### Market-Based Price Change Events

Price change events are triggered by significant price movements over sliding time windows using percentage change thresholds.

```javascript theme={null}
async function handlePriceChangeEvent(event) {
  const { token, change, trigger } = event;
  
  // Example: Notify users who hold this token
  const message = `${token.symbol} moved ${change.percentage.toFixed(1)}% over the last ${trigger.window.duration}`;
  
  // Send notifications based on your application logic
  await notifyUsers(token.address, message);
}
```

#### Available Windows

* 1h, 3h, 6h, 12h, 24h, 7d

#### Spam Prevention

Dialect's event detection includes built-in capabilities to ensure users don't receive too many alerts:

* **Debouncing & rolling averages** - Prevents rapid-fire alerts
* **Rate limits** - Controls notification frequency
* **Priority conflicts** - Manages competing events
* **Alert escalation** - Prioritizes important events

### Last Trade Price Change Events

Last trade price change events provide personalized alerts based on users' actual trading history. To use this feature, you need to [register](/alerts/events/using-events#2-2-register-users-wallets-only-for-last-trade-price-change-events) the wallets of your users.

```javascript theme={null}
async function handleLastTradePriceChangeEvent(event) {
  const { walletAddress, token, trigger, changes } = event;

  // Build contextual message based on trade history
  let message;
  const percentChange = Math.abs(changes.triggerTrade.change.percentage);
  const direction = changes.triggerTrade.change.direction;

  if (trigger.trade.type === 'buy') {
    // Alert relative to buy price
    message = `${token.symbol} is ${direction} ${percentChange.toFixed(1)}% since you bought`;
  } else if (trigger.trade.type === 'sell') {
    // Handle logic for sell events, 
    // e.g. send alert after full exit, 
    // partial sells, etc.
  }

  // Send personalized notification to specific wallet
  await sendWalletNotification(walletAddress, message);
}
```

### Key Features

* **Personalized Thresholds**: Based on market cap and position status
* **Round Trip Detection**: Alerts when returning to previous levels
* **Post-Exit Monitoring**: Continues tracking after full sells

## Trending Token Events (Coming Soon)

We're developing advanced event detection for newly launched tokens that meet specific safety and quality criteria. This system will focus on tokens with "staying power" rather than short-lived movements.

Learn more about our approach: See the [Trending Tokens Events](/alerts/events/trending-token) section for detailed information about detection criteria, safety filters, and the quality-first methodology.

<Tip>
  **Early Access Available**

  Trending token events are in development. The system is being tested internally with smart defaults before expanding to user customization.

  Contact us at [hello@dialect.to](mailto:hello@dialect.to) for early access or to discuss specific requirements.
</Tip>


# Frequently Asked Questions
Source: https://docs.dialect.to/alerts/faq

Common questions and answers about Dialect's Alert Stack.

## Getting Started

### What is the Dialect Alert Stack?

Dialect's Alert Stack is a notification infrastructure platform for Web3 applications. It enables developers to send notifications to users via multiple channels (email, Telegram, in-app, push notifications) while giving users full control over their notification preferences.

### How is Dialect different from traditional notification services?

**Key differences:**

* **Web3-native**: Built for blockchain applications with wallet-based authentication
* **User-controlled**: Users own their notification preferences, not the app
* **Multi-channel**: One API, multiple delivery methods
* **Decentralized identity**: No need for email/phone collection upfront

### Do I need to handle user signup/authentication?

No! Dialect uses **wallet-based authentication**. Users connect their Solana wallet to subscribe to notifications. No email collection or password management required.

### What chains does Dialect support?

Currently **Solana**. The system is designed to be chain-agnostic with plans to support additional chains in the future.

## Technical Integration

### How do I get started?

1. **[Register your app](/alerts/setup/register-app)** - Get API credentials
2. **[Create topics](/alerts/setup/topics-channels-subscribers)** - Define notification types
3. **[Send notifications](/alerts/send)** - Integrate sending in your app
4. **[Add subscription UI](/alerts/integrate-inbox/)** - Let users manage preferences

The [Quick Start guide](/alerts/quick-start) walks through this in \~15 minutes.

### What programming languages do you support?

* **JavaScript/TypeScript**: Full SDK and React components
* **REST API**: Any language that can make HTTP requests
* **Python**: SDK coming soon
* **Rust**: SDK planned

### Can I use Dialect without React?

**Yes!** You can:

* Use the **REST API** directly from any framework
* Use the **TypeScript SDK** in vanilla JavaScript
* Integrate with Vue, Angular, Svelte, or any frontend framework

The React components are optional convenience tools.

### How do I test notifications during development?

1. **Use test API keys** from your dashboard
2. **Send to your own wallet** for testing
3. **Check dashboard analytics** to verify delivery
4. **Use the dashboard test interface** for quick validation

Test notifications are clearly marked and don't count against quotas.

## Notification Channels

### What notification channels are available?

| Channel      | Description                           | Setup Required                         |
| ------------ | ------------------------------------- | -------------------------------------- |
| **EMAIL**    | Traditional email notifications       | None (uses Dialect's service)          |
| **TELEGRAM** | Telegram bot messages                 | Bot sends you a code                   |
| **IN\_APP**  | Notifications within your application | SDK integration                        |
| **PUSH**     | Mobile push notifications             | Firebase/APNs config (app owners only) |

### Who can send push notifications?

**Only app owners** can send push notifications to their own users. Third-party apps must use IN\_APP channel, and the app owner decides whether to show these as push notifications.

Example: A DeFi protocol (app owner) can send push notifications directly. A third-party analytics app would send IN\_APP notifications, which the protocol's mobile app could display as push notifications.

## User Experience

### How do users subscribe to notifications?

Users can subscribe through:

1. **Your app's interface** - Custom subscription UI you build
2. **Dialect's widget** - Drop-in React component
3. **Direct dashboard link** - Hosted subscription page

All methods use wallet authentication - no email/password required.

### Can users unsubscribe?

**Absolutely!** Users have full control:

* **Unsubscribe from specific topics** - Stop liquidation alerts but keep price alerts
* **Change channels** - Switch from email to Telegram
* **Unsubscribe completely** - Stop all notifications from your app

### Do users need to pay for notifications?

**No.** As of today, this service is free to use.

## Use Cases

### What types of apps use Dialect?

Common use cases:

* **DeFi Protocols**: Liquidation warnings, yield updates
* **NFT Marketplaces**: Auction alerts, collection updates
* **Trading Platforms**: Order fills, price alerts
* **Gaming**: Quest completions, leaderboard updates
* **DAOs**: Governance proposals, voting reminders

## Support

For **product support**, **partnership requests**, and **other questions** we have not covered here, email [hello@dialect.to](mailto:hello@dialect.to).


# Alerts
Source: https://docs.dialect.to/alerts/index

Get your users the notifications they need, when and where they need them.

<Tip>
  **New: Blinks in Alerts**<br />
  Send actionable alerts with embedded Blinks and let your users complete onchain transactions directly in your app. No more redirects or app switching. [Learn more](/alerts/blinks-in-alerts)
</Tip>

Dialect Alerts is a notification infrastructure that powers messaging for over 30 of the most-loved apps and wallets on Solana.

![Image with alerts delivered via multiple channels](https://res.cloudinary.com/dnxjhra4h/image/upload/f_auto,q_auto/dialect-docs/alerts-meet-anywhere.png)

## Why Dialect Alerts?

**Fast Integration** - Get notifications working in under 15 minutes with our Dashboard, REST API, TypeScript SDK, or pre-built React components. No infrastructure needed.

**Built for Web3** - Wallet-based authentication, multi-chain support, and cross-app notifications that let users see alerts from all their apps in one place.

**Complete Customization** - Full CSS control, rich content support, topics, channels, and advanced targeting to make notifications feel native to your brand exactly the way you want them.

**Enterprise Scale** - Proven performance handling 1M+ daily active users and hundreds of millions of API requests with zero downtime.

## What You Can Build

Establish a direct line of communication to your users:

* **Critical Alerts** - Liquidation warnings, security notifications, system updates
* **Smart Updates** - Price targets, portfolio changes, governance proposals
* **Engagement** - NFT activity, trading opportunities, community announcements
* **Multi-Channel Delivery** - Reach users through email, Telegram, in-app notifications, and mobile push alerts
* **Universal Inbox** - Thanks to our inbox, users can even receive notifications in the apps they already use and love

## Performance

<CardGroup>
  <Card title="1M+ Daily Active Users" icon="users">
    Handle north of 1 million DAU across our APIs for both sending alerts server-side and managing inbox feeds & user subscription preferences from the client
  </Card>

  <Card title="Hundreds of Millions of API Requests" icon="server">
    Successfully processed across our Alerts Stack in recent weeks, all without a single performance issue
  </Card>

  <Card title="Zero Downtime" icon="shield-check">
    Maintained consistent uptime even during peak usage periods
  </Card>

  <Card title="Used in Jupiter Mobile" icon="rocket" href="/alerts/mobile-alerts#real-world-example%3A-jupiter-mobile-radar">
    Powering alerts for Jupiter Mobile Radar, one of the fastest apps in crypto
  </Card>
</CardGroup>

### Time-Sensitive Alerts

Many time-sensitive alerts need to reach users quickly. We have a "burst mode" that can support orders of magnitude higher usage for up to dozens of minutes at a time:

* **Orders of Magnitude Higher Usage**: Scale up dramatically for urgent notifications
* **Extended Duration**: Maintain peak performance for up to dozens of minutes at a time
* **Real-time Processing**: Ensure critical alerts reach users without delay

### Priority Queue

A priority queue handles different kinds of delivery pipelines:

* **High priority alerts** for things like limit orders or liquidation warnings that need fast delivery
* **Lower priority** for broadcast alerts like company announcements, that can be delivered to users over longer timelines

This tiered approach ensures that urgent, actionable alerts are delivered instantly while less time-sensitive communications are processed efficiently over longer timelines.

## Getting Started Paths

### New to Alerts?

**[Quick Start Guide](/alerts/quick-start)** - With our Quick Start Guide, you can send your first notification in under 15 minutes. Learn how you can register your app, subscribe to notifications and send a test notification.

**[Try the Dashboard](https://dashboard.dialect.to)** - Send notifications immediately with no code required. Perfect for testing or one-off messages.

### Want to Send Alerts?

Sending alerts can be achieved through multiple approaches, from simple no-code solutions to powerful programmatic integrations:

**[Introduction](/alerts/send/index)** - Choose the best approach for your app:

* **[REST API](/alerts/send/api/index)**: HTTP endpoints for basic notification sending from any language or platfor incl. mobile
* **[React SDK](/alerts/send/sdk/index)**: Rich developer experience with type safety, helper functions, and UI components
* **[Dashboard](/alerts/send/dashboard)**: No-code solution for marketing and announcements
* **[Monitoring](/alerts/alerts-and-monitoring/index)**: Automated alerts based on blockchain events

### Want to Receive Alerts?

Send your users the information they need when they need it. We recommend integrating our alerts using our SDKs for the best experience.

Have a look at our inbox that lets your users also receive notifications from other apps, so they don't have to leave your app to stay informed.

**[Introduction](/alerts/integrate-inbox/index)** - Build notification experiences for your users:

* **[User Management](/alerts/integrate-inbox/user-management)**: Subscription flows and preferences
* **[API Integration](/alerts/integrate-inbox/api/index)**: Custom notification interfaces
* **[SDK Components](/alerts/integrate-inbox/sdk/setup-configuration)**: Pre-built React components
* **[Universal Inbox](/alerts/integrate-inbox/universal-inbox)**: Cross-app notification history

## Questions?

Check our [FAQ](/alerts/faq) or explore specific topics in the navigation menu.


# Authentication
Source: https://docs.dialect.to/alerts/integrate-inbox/api/authentication

Set up wallet-based user authentication for notification inbox integration using JWT tokens and client keys

## Prerequisites

Before implementing authentication, ensure you have:

* **App Registration**: Your app must be registered with Dialect ([registration guide](/alerts/setup/register-app))
* **Client Key**: Your Dialect client key (format: `dk_...`)

## Authentication Overview

Dialect uses a two-part authentication system for inbox integration:

1. **Client Key** (`X-Dialect-Client-Key`): Identifies your application
2. **JWT Token** (`Authorization: Bearer`): Authenticates the user via wallet signature

The authentication flow involves:

1. **Prepare**: Generate a message/transaction for the user to sign
2. **Sign**: User signs with their wallet
3. **Verify**: Exchange the signature for a JWT token
4. **Use**: Include the JWT token in subsequent API calls

### Flow diagram

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant API as Dialect API

    App->>API: 1. POST /v2/auth/solana/prepare
    API-->>App: Message to sign
    App->>App: 2. Sign with wallet
    App->>API: 3. POST /v2/auth/solana/verify
    API-->>App: JWT Token
    opt Verify
    App->>API: GET /v2/auth
    API-->>App: Wallet address
    end
```

## Code examples

### Step 1: Prepare Authentication

Request a message for the user to sign:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const prepareResponse = await fetch('https://alerts-api.dial.to/v2/auth/solana/prepare', {
    method: 'POST',
    headers: {
      'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      walletAddress: 'USER_WALLET_ADDRESS'
    })
  });

  const { message } = await prepareResponse.json();
  // Returns: { message: "Sign this message to authenticate. Nonce: 1638471298347" }
  ```

  ```bash cURL theme={null}
  curl -X POST https://alerts-api.dial.to/v2/auth/solana/prepare \
    -H "X-Dialect-Client-Key: YOUR_CLIENT_KEY" \
    -H "Content-Type: application/json" \
    -d '{"walletAddress": "USER_WALLET_ADDRESS"}'
  ```
</CodeGroup>

### Step 2: Sign Message

Have the user sign the message with their wallet:

```typescript theme={null}
// Using @solana/wallet-adapter
import { useWallet } from '@solana/wallet-adapter-react';

const { signMessage, publicKey } = useWallet();

const encodedMessage = new TextEncoder().encode(message);
const signature = await signMessage(encodedMessage);
const signatureBase58 = bs58.encode(signature);
```

### Step 3: Verify & Get JWT

Exchange the signature for a JWT token:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const verifyResponse = await fetch('https://alerts-api.dial.to/v2/auth/solana/verify', {
    method: 'POST',
    headers: {
      'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: message,
      signature: signatureBase58
    })
  });

  const { token } = await verifyResponse.json();
  // Store this JWT token for subsequent API calls
  // Note: JWT tokens have a 1 year lifetime
  ```

  ```bash cURL theme={null}
  curl -X POST https://alerts-api.dial.to/v2/auth/solana/verify \
    -H "X-Dialect-Client-Key: YOUR_CLIENT_KEY" \
    -H "Content-Type: application/json" \
    -d '{"message": "SIGNED_MESSAGE", "signature": "SIGNATURE_BASE58"}'
  ```
</CodeGroup>

## Making Authenticated Requests

You've setup the authentication flow. From now on, you can send requests to the API. Include both headers in all subsequent API calls:

```typescript theme={null}
const response = await fetch('https://alerts-api.dial.to/v2/history', {
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY'
  }
});
```

## Token Lifetime

JWT tokens issued through the authentication flow have a **1 year lifetime**. After this period, users will need to re-authenticate by signing a new message to obtain a fresh token.


# Integrate alerts inbox via API
Source: https://docs.dialect.to/alerts/integrate-inbox/api/index

Build notification inbox functionality using Dialect's REST API. This approach provides flexibility for applications that need server-side user management, custom authentication flows, or integration with non-JavaScript environments.

# Integrate alerts inbox via API

Build notification inbox functionality using Dialect's REST API. This approach provides flexibility for applications that need server-side user management, custom authentication flows, or integration with non-JavaScript environments.

## Why Use the REST API for Integration?

### Use-Cases

* Server-side user subscription management
* Custom authentication and user flows
* Non-React or non-TypeScript applications
* Microservices handling user notification preferences
* Backend services managing notification history and read states

### Key Capabilities

* **User Authentication**: Wallet-based authentication with JWT tokens
* **Subscription Management**: Subscribe/unsubscribe users to apps and channels
* **Topic Management**: Manage notification categories and user preferences
* **Notification History**: Retrieve, mark as read, clear, and manage user notifications
* **Push Notifications**: Complete mobile push notification setup

## Prerequisites

Before integrating the notification inbox API, ensure you have completed:

* **App Registration**: Your app must be registered with Dialect ([registration guide](/alerts/setup/register-app))
* **Client Key**: Obtain your client key for API authentication

## Integration Guide

Follow this recommended implementation flow:

1. **[Authentication](/alerts/integrate-inbox/api/authentication)** - Set up wallet-based user authentication using JWT tokens and client keys
2. **[User Management](/alerts/integrate-inbox/user-management)** - Understand subscription, channel, and topic management (see API tabs in each section)
3. **[Notifications](/alerts/integrate-inbox/api/notifications)** - Retrieve notification history and manage read states
4. **[Push Notifications](/alerts/integrate-inbox/api/push-notifications)** - Complete mobile push notification integration

## API vs SDK vs Components

**Choose the API approach when you need:**

* ✅ Server-side user management
* ✅ Custom authentication flows
* ✅ Non-JavaScript/React environments
* ✅ Microservices architecture
* ✅ Full control over user data and flows

**Consider the alternatives:**

* **[React Components](/alerts/integrate-inbox/sdk/setup-configuration)** - For frontend React applications with built-in UI
* **[TypeScript SDK](/alerts/integrate-inbox/sdk/setup-configuration)** - For frontend applications needing programmatic control

## What's Next?

Ready to start building? Begin with [Authentication](/alerts/integrate-inbox/api/authentication) to set up wallet-based user authentication, then explore the comprehensive user management capabilities in our [User Management guide](/alerts/integrate-inbox/user-management).


# Notifications
Source: https://docs.dialect.to/alerts/integrate-inbox/api/notifications

Retrieve and manage user notification history, read states, and notification data via API for building custom inbox experiences

## Prerequisites

Before managing notifications, ensure you have:

* **App Registration**: Your app must be registered with Dialect ([registration guide](/alerts/setup/register-app))
* **User Authentication**: Users must be authenticated with JWT tokens ([authentication guide](/alerts/integrate-inbox/api/authentication))

## Best Practices

<CardGroup>
  <Card title="Performance" icon="gauge">
    Use pagination (25-50 per page), cache data, and implement virtual scrolling for large lists.
  </Card>

  <Card title="User Experience" icon="heart">
    Show unread counts, "mark all read" buttons, and relative timestamps with graceful empty states.
  </Card>

  <Card title="Real-time Updates" icon="rotate">
    Poll summary endpoint periodically and update local state optimistically when marking as read.
  </Card>
</CardGroup>

## Notification History

### Get Full Notification History

Retrieve paginated notification history for the authenticated user:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch('https://alerts-api.dial.to/v2/history?limit=25', {
    headers: {
      'Authorization': `Bearer ${jwtToken}`,
      'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY'
    }
  });

  const data = await response.json();
  ```

  ```bash cURL theme={null}
  curl -X GET "https://alerts-api.dial.to/v2/history?limit=25" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "X-Dialect-Client-Key: YOUR_CLIENT_KEY"
  ```
</CodeGroup>

**Query Parameters:**

* `appId` (optional): Filter notifications for a specific app
* `limit` (optional): Number of notifications to return (default: 25, max: 50)
* `cursor` (optional): Base64-encoded cursor for pagination

**Response:**

```json theme={null}
{
  "notifications": [
    {
      "id": "notification-uuid",
      "title": "Swap Completed! 📈",
      "body": "Successfully swapped 100 USDC to SOL",
      "image": "https://example.com/notification-image.png",
      "timestamp": "2024-01-15T10:30:00Z",
      "readAt": null,
      "app": {
        "id": "app-uuid",
        "name": "SolTrader",
        "image": "https://example.com/app-logo.png"
      },
      "actions": [
        {
          "type": "link",
          "label": "View on Solscan",
          "url": "https://solscan.io/tx/3x7Kj9mNp..."
        }
      ],
      "data": {
        "type": "transaction",
        "transactionId": "3x7Kj9mNp...",
        "amount": "100",
        "fromToken": "USDC",
        "toToken": "SOL"
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJpZCI6ImFsZXJ0XzEyMyIsInRpbWVzdGFtcCI6MTcwNTMwNzQwMH0="
}
```

### Working with Custom Data

The `data` field in notifications contains custom key-value pairs that were included when the [alert was sent](/alerts/send/api/send-messages#step-4%3A-custom-data). This data is perfect for implementing deep linking, passing transaction context, or routing users to specific screens in your application.

**Example from the response above:**

```json theme={null}
"data": {
  "type": "transaction",
  "transactionId": "3x7Kj9mNp...",
  "amount": "100",
  "fromToken": "USDC",
  "toToken": "SOL"
}
```

**Common use cases:**

```typescript theme={null}
// Example 1: Navigate to transaction screen in your app
if (notification.data?.type === 'transaction') {
  navigateToTransaction({
    transactionId: notification.data.transactionId,
    amount: notification.data.amount,
    fromToken: notification.data.fromToken,
    toToken: notification.data.toToken
  });
}

// Example 2: Open external block explorer
if (notification.data?.transactionId) {
  openExternalUrl(`https://solscan.io/tx/${notification.data.transactionId}`);
}
```

<Note>
  The `data` object is optional. Not all notifications will include custom data. Always check if it exists before accessing its properties. For more information see also the [OpenAPI specification](/api-reference/integrate-an-inbox/get-notification-history)
</Note>

### Pagination Example

```typescript theme={null}
async function getAllNotifications() {
  const notifications = [];
  let cursor = null;
  let hasMore = true;

  while (hasMore) {
    const url = cursor
      ? `https://alerts-api.dial.to/v2/history?cursor=${cursor}&limit=50`
      : 'https://alerts-api.dial.to/v2/history?limit=50';

    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${jwtToken}`,
        'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY'
      }
    });

    const data = await response.json();
    notifications.push(...data.notifications);

    hasMore = data.hasMore;
    cursor = data.nextCursor;
  }

  return notifications;
}
```

### Get Notification Summary

Get unread count and summary information without full notification data:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch('https://alerts-api.dial.to/v2/history/summary', {
    headers: {
      'Authorization': `Bearer ${jwtToken}`,
      'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY'
    }
  });

  const summary = await response.json();
  ```

  ```bash cURL theme={null}
  curl -X GET "https://alerts-api.dial.to/v2/history/summary" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "X-Dialect-Client-Key: YOUR_CLIENT_KEY"
  ```
</CodeGroup>

**Query Parameters:**

* `appId` (optional): Filter summary for a specific app

**Response:**

```json theme={null}
{
  "unreadCount": 5,
  "lastUnreadNotification": {
    "id": "notification-uuid",
    "title": "Price Alert! 🚨",
    "body": "SOL reached your target price of $150",
    "timestamp": "2024-01-15T14:20:00Z",
    "app": {
      "id": "app-uuid",
      "name": "PriceTracker"
    }
  }
}
```

### Mark Notifications as Read

Mark all notifications as read for the authenticated user:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch('https://alerts-api.dial.to/v2/history/read', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${jwtToken}`,
      'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      appId: 'YOUR_APP_ID' // Optional: mark as read for specific app only
    })
  });
  ```

  ```bash cURL theme={null}
  curl -X POST "https://alerts-api.dial.to/v2/history/read" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "X-Dialect-Client-Key: YOUR_CLIENT_KEY" \
    -H "Content-Type: application/json" \
    -d '{"appId": "YOUR_APP_ID"}'
  ```
</CodeGroup>

**Request Body:**

* `appId` (optional): If provided, only marks notifications from this app as read

**Response:**

```json theme={null}
{}
```

### Clear Notification History

Clear all notifications for the authenticated user. This is a global action that applies across all clients:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch('https://alerts-api.dial.to/v2/history/clear', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${jwtToken}`,
      'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      appId: 'YOUR_APP_ID' // Optional: clear notifications for specific app only
    })
  });
  ```

  ```bash cURL theme={null}
  curl -X POST "https://alerts-api.dial.to/v2/history/clear" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "X-Dialect-Client-Key: YOUR_CLIENT_KEY" \
    -H "Content-Type: application/json" \
    -d '{"appId": "YOUR_APP_ID"}'
  ```
</CodeGroup>

**Request Body:**

* `appId` (optional): Single app ID, array of app IDs, or omitted to clear notifications from all apps

**Response:**

```json theme={null}
{}
```

## Working with Blink Actions

Alerts can now include blinks, enabling users to complete onchain transactions directly from your notification feed. This works as a two-step process:

<Steps>
  <Step title="Context Enrichment">
    When [Dialect's mapping service](/alerts/blinks-in-alerts#mapping-service) detects supported protocol URLs in notification actions, it automatically enriches them with a `context` object containing:

    * `type`: The kind of data available (e.g., `"position"` for lending/borrowing positions)
    * `apiUrl`: A pre-filled API endpoint to fetch detailed data
    * `action`: The suggested action for the user
  </Step>

  <Step title="Data Fetching">
    Your client uses the `context.apiUrl` to fetch detailed data. The response structure depends on the `context.type`. For `type: "position"`, you'll receive position and market data from our Markets API, including blink URLs for onchain actions.
  </Step>
</Steps>

<Note>
  Always check the `context.type` field to determine how to handle the data. Additional context types will be supported in the future beyond the current `"position"` type.
</Note>

In the following examples, we'll use Jupiter Borrow (a `type: "position"` context) to demonstrate this flow.

### Detecting Blink-Enabled Notifications

Check if a notification has blink context by looking for the `context` object in actions. When present, check the `type` field to determine how to handle the data:

```typescript {11-15} theme={null}
// Notification with blink context
const notification = {
  "id": "notification-uuid",
  "title": "Liquidation Warning",
  "body": "Your SOL/USDC position is at 78% LTV, approaching liquidation threshold of 80%.",
  "timestamp": "2024-01-15T10:30:00Z",
  "actions": [{
    "type": "link",
    "label": "Add Collateral",
    "url": "https://jup.ag/lend/borrow/1/nfts/2433",
    "context": {
      "type": "position",
      "apiUrl": "https://markets.dial.to/api/v0/positions/owners?walletAddresses=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176&bundleIds=jupiter.borrow.1.2433",
      "action": "deposit"
    }
  }]
};

// Check if action has blink context and get the type
const action = notification.actions?.[0];
if (action?.context) {
  const contextType = action.context.type; // e.g., "position"

  // Handle based on context type
  if (contextType === 'position') {
    // Fetch position data from Markets API
    fetchPositionData(action.context.apiUrl);
  }
  // Future context types can be added here
}
```

The `context` object is only present when Dialect's mapping service detects a supported protocol URL. Always check `context.type` to handle different data structures appropriately.

### Fetching Position Data

For `type: "position"` contexts, use the `apiUrl` to fetch position and market data from the [Markets and Positions API](/api-reference/positions/list-all-market-positions-by-wallet-address):

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    async function fetchPositionData(apiUrl: string) {
      const response = await fetch(apiUrl, {
        headers: {
          'x-dialect-api-key': 'pk_demo'
        }
      });

      const data = await response.json();
      return data.positions; // Array of positions (deposit/borrow sides)
    }

    // Usage
    const action = notification.actions[0];
    const positions = await fetchPositionData(action.context.apiUrl);

    // Find the deposit position
    const depositPosition = positions.find(p => p.side === 'deposit');

    // Access position data (more examples below)
    console.log('LTV:', depositPosition.ltv);
    console.log('Amount:', depositPosition.amount, depositPosition.market.token.symbol);
    console.log('Liquidation Price:', depositPosition.liquidationPrice);

    // Get blink URL for deposit action
    const blinkUrl = depositPosition.actions.deposit.blinkUrl;
    // blink:https://jupiter.dial.to/api/v0/lend/borrow/1/deposit?positionId=2433
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl 'https://markets.dial.to/api/v0/positions/owners?walletAddresses=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176&bundleIds=jupiter.borrow.1.2433' \
      --header 'x-dialect-api-key: pk_demo'
    ```
  </Tab>
</Tabs>

### Response Structure

The [Markets and Positions API](/api-reference/positions/list-all-market-positions-by-wallet-address) returns an array of positions. For a lending position like Jupiter Borrow, you'll receive both deposit and borrow sides as well as all relevant market data:

```json theme={null}
{
  "positions": [
    {
      "id": "jupiter.borrow.1.2433.deposit",
      "type": "lending",
      "marketId": "jupiter.borrow.1",
      "ownerAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
      "bundleId": "jupiter.borrow.1.2433",
      "side": "deposit",
      "additionalData": {
        "vaultId": 1,
        "nftId": 2433
      },
      "actions": {
        "deposit": {
          "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/deposit?positionId=2433"
        },
        "withdraw": {
          "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/2433/withdraw"
        }
      },
      "amount": 0.015060007,
      "amountUsd": 3.34,
      "ltv": 0.3033,
      "liquidationPrice": 84.00917409932147,
      "market": {
        "id": "jupiter.borrow.1",
        "type": "lending",
        "provider": {
          "id": "jupiter",
          "name": "Jupiter",
          "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/5c23c065-89ef-413b-8deb-6d8c6a849300/public"
        },
        "token": {
          "address": "So11111111111111111111111111111111111111112",
          "symbol": "WSOL",
          "decimals": 9,
          "icon": "https://coin-images.coingecko.com/coins/images/21629/large/solana.jpg?1696520989"
        },
        "borrowToken": {
          "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "symbol": "USDC",
          "decimals": 6,
          "icon": "https://coin-images.coingecko.com/coins/images/6319/large/usdc.png?1696506694"
        },
        "websiteUrl": "https://jup.ag/lend/borrow/1",
        "depositApy": 0.0784,
        "baseDepositApy": 0.0484,
        "borrowApy": 0.0597,
        "baseBorrowApy": 0.0597,
        "totalDeposit": 665220.958436127,
        "totalDepositUsd": 147340132.39,
        "totalBorrow": 80014008.8212,
        "totalBorrowUsd": 79990184.41,
        "maxBorrow": 120021000.673021,
        "maxLtv": 0.75,
        "liquidationLtv": 0.8,
        "liquidationPenalty": 0.01,
        "additionalData": {},
        "actions": {
          "deposit": {
            "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/deposit"
          }
        }
      }
    },
    {
      "id": "jupiter.borrow.1.2433.borrow",
      "type": "lending",
      "marketId": "jupiter.borrow.1",
      "ownerAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
      "bundleId": "jupiter.borrow.1.2433",
      "side": "borrow",
      "additionalData": {
        "vaultId": 1,
        "nftId": 2433
      },
      "actions": {
        "borrow": {
          "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/2433/borrow"
        },
        "repay": {
          "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/2433/repay"
        }
      },
      "amount": 1.012143,
      "amountUsd": 1.01,
      "ltv": 0.3033,
      "liquidationPrice": 84.00917409932147,
      "market": {
        "id": "jupiter.borrow.1",
        "type": "lending",
        "provider": {
          "id": "jupiter",
          "name": "Jupiter",
          "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/5c23c065-89ef-413b-8deb-6d8c6a849300/public"
        },
        "token": {
          "address": "So11111111111111111111111111111111111111112",
          "symbol": "WSOL",
          "decimals": 9,
          "icon": "https://coin-images.coingecko.com/coins/images/21629/large/solana.jpg?1696520989"
        },
        "borrowToken": {
          "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "symbol": "USDC",
          "decimals": 6,
          "icon": "https://coin-images.coingecko.com/coins/images/6319/large/usdc.png?1696506694"
        },
        "websiteUrl": "https://jup.ag/lend/borrow/1",
        "depositApy": 0.0784,
        "baseDepositApy": 0.0484,
        "borrowApy": 0.0597,
        "baseBorrowApy": 0.0597,
        "totalDeposit": 665220.958436127,
        "totalDepositUsd": 147340132.39,
        "totalBorrow": 80014008.8212,
        "totalBorrowUsd": 79990184.41,
        "maxBorrow": 120021000.673021,
        "maxLtv": 0.75,
        "liquidationLtv": 0.8,
        "liquidationPenalty": 0.01,
        "additionalData": {},
        "actions": {
          "deposit": {
            "blinkUrl": "blink:https://jupiter.dial.to/api/v0/lend/borrow/1/deposit"
          }
        }
      }
    }
  ]
}
```

### Using the Data

The response includes everything needed to build feature rich UIs ranging from simple notification buttons to detailed position management screens. Use the data to create cards, input interfaces, action buttons, and more.

#### UI Component Examples

Here are examples of different UI patterns you can build using the data from the example above. Each component uses specific fields from the API response to create rich, informative interfaces:

**Position Widget**

A compact position summary card showing key metrics at a glance.

<img alt="Position widget showing compact position metrics" />

This widget uses:

* `market.provider.name` and `market.provider.icon` for protocol branding (e.g., "Jupiter")
* `market.token.symbol` and `market.token.icon` for collateral token display (e.g., "SOL")
* `market.borrowToken.symbol` and `market.borrowToken.icon` for borrowed token display (e.g., "USDC")
* `amount` and `amountUsd` from both deposit and borrow positions to show collateral and debt sizes
* `ltv` for position health indicator (e.g., "Very Risky 78%")
* `market.websiteUrl` for the external link to the protocol

**Market Cards**

Display multiple sides of a market in an easy to understand and actionable card layout.

<img alt="Cards showing multiple options for a market" />

These cards use:

* `market.token.symbol` and `market.token.icon` for collateral display (e.g., "SOL")
* `market.borrowToken.symbol` and `market.borrowToken.icon` for debt display (e.g., "USDC")
* `amount` and `amountUsd` from deposit and borrow positions for user's position sizes
* `market.depositApy` for collateral yield (e.g., "7.2% APY")
* `market.borrowApy` for borrow rate (e.g., "4.4% APY")
* `actions.deposit.blinkUrl`, `actions.withdraw.blinkUrl`, `actions.borrow.blinkUrl`, `actions.repay.blinkUrl` for action buttons

#### Available Data Fields by Group

The API response contains extensive data organized into three main categories:

<AccordionGroup>
  <Accordion title="Position Information" icon="chart-line">
    * **Protocol**: `market.provider.name`, `market.provider.icon`, `market.provider.id`
    * **Tokens**: `market.token.symbol`, `market.token.address`, `market.token.icon`, `market.borrowToken.symbol`, `market.borrowToken.address`, `market.borrowToken.icon`
    * **Health**: `ltv`, `liquidationPrice`
    * **Amounts**: `amount`, `amountUsd`
    * **Identifiers**: `id`, `bundleId`, `marketId`, `ownerAddress`
  </Accordion>

  <Accordion title="Blinks & Fallback URLs" icon="link">
    * **Blink URLs**: `actions.deposit.blinkUrl`, `actions.withdraw.blinkUrl`, `actions.borrow.blinkUrl`, `actions.repay.blinkUrl`
    * **Protocol website**: `market.websiteUrl`
  </Accordion>

  <Accordion title="Market Data" icon="database">
    * **APY rates**: `market.depositApy`, `market.baseDepositApy`, `market.borrowApy`, `market.baseBorrowApy`
    * **Liquidation**: `market.liquidationLtv`, `market.liquidationPenalty`
    * **Limits**: `market.maxLtv`, `market.maxBorrow`
    * **Totals**: `market.totalDeposit`, `market.totalDepositUsd`, `market.totalBorrow`, `market.totalBorrowUsd`
    * **Decimals**: `market.token.decimals`, `market.borrowToken.decimals`
  </Accordion>
</AccordionGroup>


# Push Notifications
Source: https://docs.dialect.to/alerts/integrate-inbox/api/push-notifications

Enable mobile push notifications to reach users instantly on their devices, even when your app was closed

## How Push Notifications Work with Dialect

<Steps>
  <Step title="Users subscribe">
    <Note>
      Please note that it is requried to subscribe your user to the [basic alerts endpoint](/api-reference/integrate-an-inbox/subscribe-to-alerts) as well to ensure push notifications are delivered.
    </Note>

    Users subscribe to push notifications via your app or notification components via the [push notification endpoint](/api-reference/integrate-an-inbox/subscribe-to-push-notifications).
  </Step>

  <Step title="Dialect routes notifications">
    If event occurs, Dialect sends notifications to subscribed users and triggers the send process
  </Step>

  <Step title="Firebase Cloud Messaging (FCM) sends notifications">
    Firebase handles device token management and delivers push notifications to the user's device
  </Step>
</Steps>

## Prerequisites

Before implementing push notifications with Dialect, please ensure you have completed the following steps:

1. **App Registration**: Your app must be registered with Dialect ([registration guide](/alerts/setup/register-app))
2. **User Authentication**: Users must be authenticated with JWT tokens ([authentication guide](/alerts/integrate-inbox/api/authentication))
3. **Set up Firebase Cloud Messaging** in your application
   * Follow [Firebase's documentation](https://firebase.google.com/docs/cloud-messaging) to add the Firebase SDK to your app
   * Implement the necessary code to request and receive an FCM token
4. **Implement wallet integration** for Solana signature verification
   * Your mobile app must be able to request message signing from the user's wallet
5. **Provide Service Account Credentials** to Dialect for authentication
   * Dialect uses your service account credentials to authenticate and send push notifications to your users
   * To get started, create a service account with the `cloudmessaging.messages.create` rights
   * Once created, contact us at [hello@dialect.to](mailto:hello@dialect.to) to provide your service account credentials
   * Dialect will then connect your app with our Alerts infrastructure

Once these prerequisites are in place, you can proceed with the subscription and notification flows.

## Push Subscription Flow

Once a user is authenticated, you can register their device to receive push notifications. This involves obtaining an FCM token and associating it with the user's wallet address.

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant Firebase as Firebase SDK
    participant API as Dialect API

    App->>Firebase: 1. Request FCM Token
    Firebase-->>App: FCM Token
    App->>API: 2. POST /v2/push/subscribe
    Note right of App: Send JWT + FCM Token
    API-->>App: Subscription confirmed
```

## Get FCM Token

Before you can subscribe to push notifications, you need to obtain an FCM token from Firebase:

<Tabs>
  <Tab title="React Native">
    ```typescript theme={null}
    import messaging from '@react-native-firebase/messaging';

    async function getFCMToken() {
      try {
        // Request permission (iOS)
        const authStatus = await messaging().requestPermission();
        const enabled =
          authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
          authStatus === messaging.AuthorizationStatus.PROVISIONAL;

        if (enabled) {
          // Get FCM token
          const fcmToken = await messaging().getToken();
          console.log('FCM Token:', fcmToken);
          return fcmToken;
        }
      } catch (error) {
        console.error('Failed to get FCM token:', error);
      }
    }
    ```
  </Tab>

  <Tab title="iOS (Swift)">
    ```swift theme={null}
    import Firebase

    func getFCMToken() {
      Messaging.messaging().token { token, error in
        if let error = error {
          print("Error fetching FCM registration token: \(error)")
        } else if let token = token {
          print("FCM registration token: \(token)")
          // Use this token to subscribe to Dialect push notifications
        }
      }
    }
    ```
  </Tab>

  <Tab title="Android (Kotlin)">
    ```kotlin theme={null}
    import com.google.firebase.messaging.FirebaseMessaging

    fun getFCMToken() {
      FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
        if (!task.isSuccessful) {
          Log.w(TAG, "Fetching FCM registration token failed", task.exception)
          return@addOnCompleteListener
        }

        // Get new FCM registration token
        val token = task.result
        Log.d(TAG, "FCM Token: $token")
        // Use this token to subscribe to Dialect push notifications
      }
    }
    ```
  </Tab>

  <Tab title="Web">
    ```javascript theme={null}
    import { getMessaging, getToken } from 'firebase/messaging';

    async function getFCMToken() {
      const messaging = getMessaging();
      try {
        const currentToken = await getToken(messaging, {
          vapidKey: 'YOUR_VAPID_KEY'
        });
        if (currentToken) {
          console.log('FCM Token:', currentToken);
          return currentToken;
        } else {
          console.log('No registration token available.');
        }
      } catch (err) {
        console.log('An error occurred while retrieving token. ', err);
      }
    }
    ```
  </Tab>
</Tabs>

For more detailed implementation instructions, visit the Firebase Cloud Messaging documentation for [iOS](https://firebase.google.com/docs/cloud-messaging/ios/client), [Android](https://firebase.google.com/docs/cloud-messaging/android/client), and [Web](https://firebase.google.com/docs/cloud-messaging/js/client).

## Push Subscription Management

### Subscribe to Push Notifications

Once you have an FCM token, subscribe the user to push notifications:

```typescript theme={null}
async function subscribeToDialectPush(fcmToken: string, jwtToken: string, clientKey: string) {
  try {
    const response = await fetch('https://alerts-api.dial.to/v2/push/subscribe', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${jwtToken}`,
        'X-Dialect-Client-Key': clientKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        fcmToken: fcmToken,
        deviceId: 'unique-device-identifier', // Optional but recommended
        appId: 'YOUR_APP_ID' // Optional - for app-specific subscriptions
      })
    });

    if (response.ok) {
      console.log('Successfully subscribed to push notifications');
    } else {
      console.error('Failed to subscribe to push notifications');
    }
  } catch (error) {
    console.error('Push subscription error:', error);
  }
}
```

**Parameters:**

* `fcmToken`: Firebase Cloud Messaging token from your mobile app
* `deviceId`: (Optional) Unique device identifier for managing devices
* `appId`: (Optional) Subscribe to pushes for specific app only

### Unsubscribe from Push Notifications

```typescript theme={null}
async function unsubscribeFromDialectPush(fcmToken: string, jwtToken: string, clientKey: string) {
  try {
    const response = await fetch('https://alerts-api.dial.to/v2/push/unsubscribe', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${jwtToken}`,
        'X-Dialect-Client-Key': clientKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        fcmToken: fcmToken,
        deviceId: 'unique-device-identifier', // Should match subscription
        appId: 'YOUR_APP_ID' // Optional
      })
    });

    if (response.ok) {
      console.log('Successfully unsubscribed from push notifications');
    }
  } catch (error) {
    console.error('Push unsubscription error:', error);
  }
}
```

## Handling Push Notifications

### Processing Received Notifications

<Tabs>
  <Tab title="React Native">
    ```typescript theme={null}
    import messaging from '@react-native-firebase/messaging';
    import { useEffect } from 'react';

    export function usePushNotifications() {
      useEffect(() => {
        // Handle notifications when app is in foreground
        const unsubscribeForeground = messaging().onMessage(async remoteMessage => {
          console.log('Foreground notification:', remoteMessage);
          
          // Show in-app notification or update notification list
          handleDialectNotification(remoteMessage);
        });

        // Handle notifications when app is opened from background
        const unsubscribeBackground = messaging().onNotificationOpenedApp(remoteMessage => {
          console.log('Background notification opened:', remoteMessage);
          
          // Navigate to specific screen or perform action
          handleNotificationAction(remoteMessage);
        });

        // Handle notifications when app is opened from quit state
        messaging()
          .getInitialNotification()
          .then(remoteMessage => {
            if (remoteMessage) {
              console.log('App opened from quit state:', remoteMessage);
              handleNotificationAction(remoteMessage);
            }
          });

        return () => {
          unsubscribeForeground();
          unsubscribeBackground();
        };
      }, []);
    }

    function handleDialectNotification(remoteMessage: any) {
      const { notification, data } = remoteMessage;
      
      // Dialect notifications include:
      // - notification.title
      // - notification.body  
      // - notification.image (optional)
      // - data.* (custom data from sender)
      
      console.log('Notification title:', notification?.title);
      console.log('Notification body:', notification?.body);
      console.log('Custom data:', data);
      
      // Update your notification state/context
      // addNotificationToInbox(remoteMessage);
    }

    function handleNotificationAction(remoteMessage: any) {
      const { data } = remoteMessage;
      
      // Handle deep linking based on notification data
      if (data?.action === 'open_trade') {
        // Navigate to trade screen
        navigateToTrade(data.tradeId);
      } else if (data?.action === 'open_profile') {
        // Navigate to profile screen
        navigateToProfile(data.userId);
      }
    }
    ```
  </Tab>

  <Tab title="iOS (Swift)">
    ```swift theme={null}
    import UserNotifications

    class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
      
      // Handle notifications when app is in foreground
      func userNotificationCenter(_ center: UNUserNotificationCenter,
                                  willPresent notification: UNNotification,
                                  withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        
        let userInfo = notification.request.content.userInfo
        handleDialectNotification(userInfo: userInfo)
        
        // Show notification banner
        completionHandler([.banner, .sound, .badge])
      }
      
      // Handle notification taps
      func userNotificationCenter(_ center: UNUserNotificationCenter,
                                  didReceive response: UNNotificationResponse,
                                  withCompletionHandler completionHandler: @escaping () -> Void) {
        
        let userInfo = response.notification.request.content.userInfo
        handleNotificationAction(userInfo: userInfo)
        
        completionHandler()
      }
      
      func handleDialectNotification(userInfo: [AnyHashable: Any]) {
        // Extract notification data
        let title = userInfo["gcm.notification.title"] as? String
        let body = userInfo["gcm.notification.body"] as? String
        
        print("Notification: \(title ?? "") - \(body ?? "")")
        
        // Update your app state
        // NotificationManager.shared.addNotification(userInfo)
      }
      
      func handleNotificationAction(userInfo: [AnyHashable: Any]) {
        // Handle deep linking
        if let action = userInfo["action"] as? String {
          switch action {
          case "open_trade":
            if let tradeId = userInfo["tradeId"] as? String {
              navigateToTrade(tradeId: tradeId)
            }
          case "open_profile":
            if let userId = userInfo["userId"] as? String {
              navigateToProfile(userId: userId)
            }
          default:
            break
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Android (Kotlin)">
    ```kotlin theme={null}
    import com.google.firebase.messaging.FirebaseMessagingService
    import com.google.firebase.messaging.RemoteMessage

    class MyFirebaseMessagingService : FirebaseMessagingService() {
        
        override fun onMessageReceived(remoteMessage: RemoteMessage) {
            super.onMessageReceived(remoteMessage)
            
            // Handle Dialect notification
            handleDialectNotification(remoteMessage)
        }
        
        private fun handleDialectNotification(remoteMessage: RemoteMessage) {
            val notification = remoteMessage.notification
            val data = remoteMessage.data
            
            Log.d(TAG, "Notification title: ${notification?.title}")
            Log.d(TAG, "Notification body: ${notification?.body}")
            Log.d(TAG, "Notification data: $data")
            
            // Create and show notification
            createNotification(
                title = notification?.title ?: "New Notification",
                body = notification?.body ?: "",
                data = data
            )
        }
        
        private fun createNotification(title: String, body: String, data: Map<String, String>) {
            val intent = Intent(this, MainActivity::class.java).apply {
                flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK
                
                // Add notification data for deep linking
                data.forEach { (key, value) ->
                    putExtra(key, value)
                }
            }
            
            val pendingIntent = PendingIntent.getActivity(
                this, 0, intent, PendingIntent.FLAG_IMMUTABLE
            )
            
            val notification = NotificationCompat.Builder(this, CHANNEL_ID)
                .setSmallIcon(R.drawable.ic_notification)
                .setContentTitle(title)
                .setContentText(body)
                .setAutoCancel(true)
                .setContentIntent(pendingIntent)
                .build()
            
            val notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
            notificationManager.notify(System.currentTimeMillis().toInt(), notification)
        }
    }
    ```
  </Tab>
</Tabs>

## Push Notification Data Structure

Dialect push notifications include standard notification content plus custom data:

```json theme={null}
{
  "notification": {
    "title": "Trade Executed! 📈",
    "body": "Your buy order for 10 SOL has been executed at $142.50",
    "image": "https://example.com/notification-image.png"
  },
  "data": {
    "action": "open_trade",
    "tradeId": "123",
    "amount": "10",
    "price": "142.50",
    "appId": "your-app-id",
    "notificationId": "notification-uuid"
  }
}
```

## Advanced Configuration

### App-Specific Push Subscriptions

Subscribe to push notifications for specific apps only:

```typescript theme={null}
// Subscribe to pushes for all apps (default)
await subscribeToDialectPush(fcmToken, jwtToken, clientKey);

// Subscribe to pushes for specific app only
await subscribeToDialectPush(fcmToken, jwtToken, clientKey, deviceId, 'specific-app-id');
```

### Notification Categories and Topics

Push notifications respect user subscription preferences:

* **Channel subscriptions**: Users must be subscribed to apps via channels (IN\_APP, EMAIL, etc.)
* **Topic subscriptions**: If your app uses topics, push notifications will only be sent for subscribed topics
* **Push preference**: Users must specifically enable push notifications

### Custom Push Behavior

Configure push notification behavior:

```typescript theme={null}
// Send push notification with custom configuration
const notificationData = {
  recipient: {
    type: 'subscriber',
    walletAddress: 'USER_WALLET_ADDRESS'
  },
  channels: ['PUSH', 'IN_APP'],
  message: {
    title: 'Custom Push Notification',
    body: 'This includes custom data and actions'
  },
  push: {
    playNotificationSound: true,    // Play sound (default: true)
    showNotification: true          // Show UI notification (default: true)
  },
  data: {
    action: 'custom_action',
    deepLink: '/custom-path',
    customField: 'custom-value'
  }
};
```

## Troubleshooting

### Common Issues

**Push notifications not received:**

* Verify FCM token is valid and current
* Check if user is subscribed to push notifications via Dialect
* Ensure app has notification permissions
* Verify Firebase project configuration

**Authentication errors:**

* Ensure JWT token is valid and not expired
* Verify client key is correct
* Check if user has proper permissions

**iOS-specific issues:**

* Verify APNs certificate is properly configured in Firebase
* Check iOS notification permissions
* Ensure app is properly signed for push notifications

## Best Practices

<Tip>
  **User Experience**: Request push permission at the right moment (not immediately on app launch), clearly explain the value of push notifications, provide easy opt-out options, and handle permission denials gracefully.
</Tip>

<Tip>
  **Technical Implementation**: Keep FCM tokens updated when they change, handle token refresh properly, implement proper error handling for network failures, and use unique device IDs for better device management.
</Tip>

## Next Steps

With push notifications integrated, you have a complete notification system:

1. **[User Management](/alerts/integrate-inbox/user-management)** - Manage user subscriptions and preferences
2. **[Notification History](/alerts/integrate-inbox/api/notifications)** - Retrieve and display notification history
3. **[Authentication](/alerts/integrate-inbox/api/authentication)** - Handle user authentication flows

Your users can now receive notifications via in-app messages, email, and push notifications across all their devices!


# Introduction
Source: https://docs.dialect.to/alerts/integrate-inbox/index

Integrate notification inboxes into your applications to let users view, manage, and interact with their notifications across multiple apps and channels. Dialect provides flexible integration options to fit different technical requirements and use cases.

![Image with alerts delivered via multiple channels](https://res.cloudinary.com/dnxjhra4h/image/upload/f_auto,q_auto/dialect-docs/alerts-meet-anywhere.png)

## Integration Options

Choose the approach that best fits your application architecture:

### 🎨 React Components (Recommended)

Pre-built React components for quick integration with minimal setup. Perfect for React applications that want a complete notification experience out of the box.

* **NotificationsButton**: Complete done-for-you solution with built-in UI
* **Notifications**: Standalone component with full styling control
* Built-in user management and authentication flows

**[Get started with React Components →](/alerts/integrate-inbox/sdk/setup-configuration)**

### 🔧 REST API

Direct API integration for maximum flexibility and control. Ideal for server-side implementations, custom authentication flows, or non-JavaScript environments.

* Wallet-based authentication with JWT tokens
* Complete subscription and topic management
* Notification history and read state management
* Mobile push notification setup

**[Get started with REST API →](/alerts/integrate-inbox/api/index)**

### 🌐 Universal Inbox

Enable cross-app notifications where users can subscribe to multiple applications and receive all their notifications in one unified feed.

* Subscribe to notifications from multiple apps (Drift, Bonk, Sanctum, etc.)
* Single notification feed across the entire ecosystem
* User-controlled cross-app messaging experience

**[Learn about Universal Inbox →](/alerts/integrate-inbox/universal-inbox)**

## Key Features

**📱 Multi-Channel Delivery**

* In-app notifications with real-time updates
* Mobile push notifications via Firebase
* Email notifications for important updates

**🎯 User Control**

* Granular subscription management per app and channel
* Topic-based notification categories
* Read/unread state management

**🔐 Secure Authentication**

* Solana wallet-based authentication
* JWT token management
* Client key authorization

**📊 Complete History**

* Paginated notification history
* Cross-app message aggregation
* Filtering and search capabilities

## Prerequisites

Before integrating notification inboxes, ensure you have:

1. **App Registration**: Your app must be registered with Dialect ([registration guide](/alerts/setup/register-app))
2. **Client Key**: Obtain your client key for API authentication
3. **User Wallet Integration**: Ability to request wallet signatures for authentication

## User Management Foundation

All integration approaches build on the same user management system. Understanding these concepts is crucial regardless of your chosen integration method:

**[User Management Guide →](/alerts/integrate-inbox/user-management)**

## Quick Start Guide

1. **Choose Your Integration**: React Components for frontend apps, REST API for backend/custom implementations
2. **Review User Management**: Understand how subscriptions and channels work
3. **Set Up Authentication**: Implement wallet-based user authentication
4. **Build Notification Features**: Display notifications, manage subscriptions, handle push notifications
5. **Consider Universal Inbox**: Enable cross-app notifications for enhanced user experience

## What's Next?

* **New to Dialect?** Start with [User Management](/alerts/integrate-inbox/user-management) to understand the foundation
* **Building a React app?** Jump to [React Components](/alerts/integrate-inbox/sdk/setup-configuration)
* **Need API control?** Begin with [REST API](/alerts/integrate-inbox/api/index)
* **Want cross-app notifications?** Explore [Universal Inbox](/alerts/integrate-inbox/universal-inbox)


# Notifications
Source: https://docs.dialect.to/alerts/integrate-inbox/sdk/notifications

Standalone notification feed component with complete styling control via CSS variables, perfect for embedding in custom layouts, modals, or sidebars

## Overview

`Notifications` gives you maximum flexibility:

* **Headless component** - no built-in button or modal
* **Full CSS control** via CSS custom properties
* **Embed anywhere** - sidebars, modals, dedicated pages
* **Complete brand integration** with custom themes
* **Advanced styling** for individual notification types

**Choose this component if you want:**

* ✅ Complete design control and custom styling
* ✅ Embed in your own modal, sidebar, or layout
* ✅ Full brand integration with CSS variables
* ✅ Custom notification type styling
* ❌ Need to build your own button/modal logic

## Prerequisites

Before implementing the Notifications component, ensure you have completed:

* **App Registration**: Your app must be registered with Dialect ([registration guide](/alerts/setup/register-app))
* **SDK Setup**: Configure the Dialect React SDK ([Setup & Configuration guide](/alerts/integrate-inbox/sdk/setup-configuration))
* **User Management Understanding**: Familiarize yourself with subscriptions and channels ([User Management guide](/alerts/integrate-inbox/user-management))

## Basic Usage

### Simple Integration

```tsx theme={null}
"use client";

import "@dialectlabs/react-ui/index.css";
import { DialectSolanaSdk } from "@dialectlabs/react-sdk-blockchain-solana";
import { Notifications } from "@dialectlabs/react-ui";

const DAPP_ADDRESS = process.env.NEXT_PUBLIC_DIALECT_DAPP_ADDRESS!;

export function MyNotificationFeed() {
  return (
    <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
      <div className="w-96 h-screen bg-white border-l shadow-lg">
        <Notifications />
      </div>
    </DialectSolanaSdk>
  );
}
```

### With Close Button

If you want users to be able to close the notification panel:

```tsx theme={null}
"use client";

import "@dialectlabs/react-ui/index.css";
import { DialectSolanaSdk } from "@dialectlabs/react-sdk-blockchain-solana";
import { Notifications } from "@dialectlabs/react-ui";
import { useState } from "react";

const DAPP_ADDRESS = process.env.NEXT_PUBLIC_DIALECT_DAPP_ADDRESS!;

export function NotificationPanel() {
  const [isOpen, setIsOpen] = useState(true);
  
  if (!isOpen) return null;

   return (
        <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
            {isOpen ? (
                <div className="fixed top-0 w-96 h-screen bg-white">
                    <Notifications setOpen={setIsOpen} />
                </div>
            ) : (
                <button onClick={() => setIsOpen(true)}>
                    Open Notifications
                </button>
            )}
        </DialectSolanaSdk>
   );
}
```

## Configuration Options

### Channel Configuration

Control which additional notification channels users can configure:

```tsx theme={null}
// Show all additional channels (default)
<Notifications />

// Limit to specific additional channels  
<Notifications channels={["email"]} />
```

Available additional channels:

* `"email"` - Email notifications
* `"telegram"` - Telegram bot notifications
* **In-app** - Always enabled (not configurable)

## Custom Styling

### CSS Variables Overview

The `Notifications` component uses CSS custom properties for complete theme control:

```css theme={null}
/* Import Dialect styles first */
@import url('@dialectlabs/react-ui/index.css');

.dialect {
  /* Brand colors */
  --dt-accent-brand: #09cbbf;
  --dt-accent-error: #f62d2d;
  
  /* Background colors */
  --dt-bg-primary: #ffffff;
  --dt-bg-secondary: #f9f9f9;
  --dt-bg-tertiary: #f2f3f5;
  
  /* Text colors */
  --dt-text-primary: #232324;
  --dt-text-secondary: #434445;
  --dt-text-tertiary: #737373;
  
  /* Border radius */
  --dt-border-radius-s: 0.5rem;
  --dt-border-radius-m: 0.75rem;
}
```

### Basic Brand Customization

Override CSS variables to match your brand:

```css theme={null}
.dialect {
  --dt-accent-brand: #your-brand-color;
  --dt-bg-primary: #your-background;
  --dt-text-primary: #your-text-color;
}
```

**Important:** Import order matters:

```tsx theme={null}
// ✅ Correct order
import "@dialectlabs/react-ui/index.css";  // Import first
import "./custom-dialect-styles.css";      // Then your overrides
```

### Complete CSS Variable Reference

<Tabs>
  <Tab title="Colors">
    ```css theme={null}
    .dialect {
      /* Brand & Accent */
      --dt-accent-brand: #09cbbf;
      --dt-accent-error: #f62d2d;
      --dt-brand-transparent: #b3b3b31a;
      
      /* Backgrounds */
      --dt-bg-brand: #ebebeb;
      --dt-bg-primary: #ffffff;
      --dt-bg-secondary: #f9f9f9;
      --dt-bg-tertiary: #f2f3f5;
      
      /* Buttons */
      --dt-button-primary: #2a2a2b;
      --dt-button-primary-disabled: #656564;
      --dt-button-primary-hover: #434445;
      --dt-button-secondary: #ebebeb;
      --dt-button-secondary-disabled: #f2f3f5;
      --dt-button-secondary-hover: #f2f3f5;
      
      /* Icons */
      --dt-icon-primary: #2a2a2b;
      --dt-icon-secondary: #888989;
      --dt-icon-tertiary: #b3b3b3;
      
      /* Text */
      --dt-text-accent: #08c0b4;
      --dt-text-inverse: #ffffff;
      --dt-text-primary: #232324;
      --dt-text-quaternary: #888989;
      --dt-text-secondary: #434445;
      --dt-text-tertiary: #737373;
    }
    ```
  </Tab>

  <Tab title="Spacing & Layout">
    ```css theme={null}
    .dialect {
      /* Border radius */
      --dt-border-radius-xs: 0.375rem;
      --dt-border-radius-s: 0.5rem;
      --dt-border-radius-m: 0.75rem;
      --dt-border-radius-l: 1rem;
      
      /* Borders & Strokes */
      --dt-stroke-primary: #dee1e7;
      
      /* Inputs */
      --dt-input-checked: #09cbbf;
      --dt-input-primary: #dee1e7;
      --dt-input-secondary: #ffffff;
      --dt-input-unchecked: #d7d7d7;
    }
    ```
  </Tab>
</Tabs>

### Dark Theme

The component automatically applies dark theme when using the `theme` prop:

```tsx theme={null}
<Notifications theme="dark" />
```

You can also customize dark theme colors:

```css theme={null}
.dialect[data-theme="dark"] {
  --dt-accent-brand: #09cbbf;
  --dt-bg-primary: #1b1b1c;
  --dt-bg-secondary: #232324;
  --dt-bg-tertiary: #2a2a2b;
  --dt-text-primary: #ffffff;
  --dt-text-secondary: #c4c6c8;
  /* ... customize other dark theme variables */
}
```

### Auto Theme Detection

Automatically switch themes based on user preferences:

```tsx theme={null}
import { useState, useEffect } from 'react';

export function ThemeAwareNotifications() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  useEffect(() => {
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
    setTheme(mediaQuery.matches ? 'dark' : 'light');

    const handler = (e: MediaQueryListEvent) => {
      setTheme(e.matches ? 'dark' : 'light');
    };
    
    mediaQuery.addEventListener('change', handler);
    return () => mediaQuery.removeEventListener('change', handler);
  }, []);

  return (
    <div data-theme={theme}>
      <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
        <Notifications theme={theme} />
      </DialectSolanaSdk>
    </div>
  );
}
```

## Layout Integration Examples

### Sidebar Integration

```tsx theme={null}
export function AppWithNotificationSidebar() {
  const [showNotifications, setShowNotifications] = useState(false);

  return (
    <div className="flex h-screen">
      <main className="flex-1 p-6">
        <button 
          onClick={() => setShowNotifications(!showNotifications)}
          className="bg-blue-500 text-white px-4 py-2 rounded"
        >
          {showNotifications ? 'Hide' : 'Show'} Notifications
        </button>
      </main>
      
      {showNotifications && (
        <aside className="w-96 border-l bg-gray-50">
          <div className="p-4 border-b">
            <h2 className="text-lg font-semibold">Notifications</h2>
          </div>
          
          <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
            <Notifications setOpen={setShowNotifications} />
          </DialectSolanaSdk>
        </aside>
      )}
    </div>
  );
}
```

### Modal Integration

```tsx theme={null}
import { Dialog } from '@headlessui/react';

export function NotificationModal() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button 
        onClick={() => setIsOpen(true)}
        className="relative p-2 rounded-full bg-gray-100"
      >
        🔔
      </button>

      <Dialog open={isOpen} onClose={setIsOpen}>
        <div className="fixed inset-0 bg-black/30" />
        <div className="fixed inset-0 flex items-center justify-center p-4">
          <Dialog.Panel className="bg-white rounded-lg w-96 h-96">
            <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
              <Notifications setOpen={setIsOpen} />
            </DialectSolanaSdk>
          </Dialog.Panel>
        </div>
      </Dialog>
    </>
  );
}
```

### Full Page Integration

```tsx theme={null}
export function NotificationsPage() {
  return (
    <div className="min-h-screen bg-gray-50">
      <header className="bg-white border-b px-6 py-4">
        <h1 className="text-2xl font-bold">Your Notifications</h1>
      </header>
      
      <main className="max-w-2xl mx-auto p-6">
        <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
          <Notifications />
        </DialectSolanaSdk>
      </main>
    </div>
  );
}
```

## Troubleshooting

**Styling not applying:**

* Ensure CSS import order is correct
* Check CSS specificity - you may need `!important`
* Verify CSS variables are defined on `.dialect` class

**Component not displaying:**

* Verify `dappAddress` is correct and app is registered
* Check wallet connection status
* Ensure parent container has appropriate dimensions

**Performance issues:**

* Consider lazy loading for modals/conditional displays
* Use CSS containment for better rendering performance
* Implement virtualization for large notification lists

## Next Steps

* **Need a simpler solution?** Use the [NotificationsButton component](/alerts/integrate-inbox/sdk/notifications-button)
* **Want to send notifications?** Check the [Send SDK documentation](/alerts/send/)

The `Notifications` component provides complete control over notification display and styling, perfect for creating fully branded notification experiences.


# NotificationsButton
Source: https://docs.dialect.to/alerts/integrate-inbox/sdk/notifications-button

Complete, done-for-you notification solution with built-in notification bell button, modal, user settings panel, and notification history

## Overview

`NotificationsButton` includes everything you need for user notifications:

* **Notification bell icon** with unread count badge
* **Responsive modal** that opens when clicked
* **User settings panel** for channel and topic management
* **Notification history** with read/unread states
* **Built-in authentication** and wallet integration

**Choose this component if you want:**

* ✅ Quick setup with minimal configuration
* ✅ Professional notification UI out of the box
* ✅ Built-in responsive design (mobile + desktop)
* ✅ Light/dark theme options
* ❌ Limited visual customization (theme prop only)

## Prerequisites

Before implementing the NotificationsButton component, ensure you have completed:

* **App Registration**: Your app must be registered with Dialect ([registration guide](/alerts/setup/register-app))
* **SDK Setup**: Configure the Dialect React SDK ([Setup & Configuration guide](/alerts/integrate-inbox/sdk/setup-configuration))
* **User Management Understanding**: Familiarize yourself with subscriptions and channels ([User Management guide](/alerts/integrate-inbox/user-management))

## Basic Usage

It is important that the `NotificationsButton` is always wrapped around the client SDK. We recommend writing a small component to ensure it is always the case.

### Simple Integration

```tsx theme={null}
"use client";

import "@dialectlabs/react-ui/index.css";
import { DialectSolanaSdk } from "@dialectlabs/react-sdk-blockchain-solana";
import { NotificationsButton } from "@dialectlabs/react-ui";

const DAPP_ADDRESS = process.env.NEXT_PUBLIC_DIALECT_DAPP_ADDRESS!;

export function MyNotificationButton() {
  return (
    <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
      <NotificationsButton />
    </DialectSolanaSdk>
  );
}
```

### Theme Options

Control the visual theme of the notification button and modal:

<Tabs>
  <Tab title="Light Theme">
    ```tsx theme={null}
    <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
      <NotificationsButton theme="light" />
    </DialectSolanaSdk>
    ```
  </Tab>

  <Tab title="Dark Theme">
    ```tsx theme={null}
    <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
      <NotificationsButton theme="dark" />
    </DialectSolanaSdk>
    ```
  </Tab>
</Tabs>

### Channel Configuration

Control which additional notification channels users can configure. In-app notifications are always enabled by default.

```tsx theme={null}
// Show all channels (default - includes email and telegram options)
<NotificationsButton />

// Limit to specific channels
<NotificationsButton channels={["email"]} />
```

Available channels:

* `"email"` - Email notifications
* `"telegram"` - Telegram bot notifications
* **In-app** - Always enabled (not configurable)

### Custom Button

Replace the default notification bell with your own button component:

```tsx theme={null}
import { NotificationsButton } from "@dialectlabs/react-ui";

export function CustomButtonNotifications() {
  return (
    <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
      <NotificationsButton>
        {({ open, setOpen, unreadCount, ref }) => (
          <button 
            ref={ref} 
            onClick={() => setOpen(!open)}
            className="custom-notification-button"
          >
            <span>Notifications</span>
            {unreadCount > 0 && (
              <span className="badge">{unreadCount}</span>
            )}
          </button>
        )}
      </NotificationsButton>
    </DialectSolanaSdk>
  );
}
```

**Render prop parameters:**

* `open` - Boolean indicating if modal is open
* `setOpen` - Function to control modal state
* `unreadCount` - Number of unread notifications
* `ref` - Required ref for the button element

### Custom Modal

Replace the default modal container with your own:

```tsx theme={null}
export function CustomModalNotifications() {
  return (
    <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
      <NotificationsButton
        renderModalComponent={({ open, setOpen, ref, children }) => {
          if (!open) return null;
          
          return (
            <div 
              ref={ref} 
              className="fixed inset-0 z-50 bg-black bg-opacity-50"
            >
              <div className="flex items-center justify-center min-h-screen p-4">
                <div className="bg-white rounded-lg max-w-md w-full">
                  {children}
                </div>
              </div>
            </div>
          );
        }}
      />
    </DialectSolanaSdk>
  );
}
```

**Modal render prop parameters:**

* `open` - Boolean indicating if modal should be shown
* `setOpen` - Function to control modal state
* `ref` - Required ref for the modal container
* `children` - The notification content (must be rendered)

## Advanced Configuration

### Styling (Limited)

#### Available Styling Options

The `NotificationsButton` component has limited styling capabilities:

```tsx theme={null}
// ✅ Theme options
<NotificationsButton theme="light" />
<NotificationsButton theme="dark" />

// ✅ CSS class for wrapper
<NotificationsButton className="my-wrapper-class" />

// ❌ CSS variables don't affect internal styling
// ❌ Individual component styling not available
```

#### Wrapper Styling

You can style the button wrapper, but internal components use fixed styling:

```css theme={null}
.my-wrapper-class {
  /* This affects the button wrapper */
  position: relative;
  z-index: 10;
}

/* These CSS variables WON'T affect NotificationsButton */
.dialect {
  --dt-accent-brand: #custom-color; /* No effect */
  --dt-bg-primary: #custom-bg;      /* No effect */
}
```

#### For Full Styling Control

If you need complete visual customization, use the [standalone Notifications component](/alerts/integrate-inbox/sdk/notifications) instead:

```tsx theme={null}
// Full styling control with CSS variables
import { Notifications } from "@dialectlabs/react-ui";

<div className="my-custom-modal">
  <Notifications />
</div>
```

### Component Behavior

#### Responsive Design

The component automatically adapts to different screen sizes:

* **Mobile**: Full-screen modal overlay
* **Tablet/Desktop**: Positioned modal (420px × 600px)
* **Button**: Scales appropriately for touch interfaces

#### User Workflow

1. **Button Click**: User clicks notification bell
2. **Authentication**: User connects wallet (if not connected)
3. **Subscription**: User signs a message, thereby subscribes to your app
4. **Settings**: User can configure channels and topics
5. **Notifications**: User views notification history

## Troubleshooting

### Common Issues

**Button not appearing:**

* Verify `dappAddress` is correct and app is registered
* Check that styles are imported before the component
* Ensure wallet adapter is properly configured

**Modal not opening:**

* Check browser console for JavaScript errors
* Verify wallet connection is working
* Ensure `dappAddress` matches your registered app

**Styling not working:**

* CSS variables don't affect `NotificationsButton` styling
* Use the `theme` prop for basic theming
* Consider the standalone `Notifications` component for full control

**Wallet connection issues:**

* Verify wallet adapter compatibility
* Check wallet permissions and connection state
* Test with different wallet providers

### Development Tips

* Use `environment="development"` during development
* Test with different wallet providers
* Verify notification flow end-to-end
* Check network requests in browser dev tools

## Next Steps

* **Need full styling control?** Use the [standalone Notifications component](/alerts/integrate-inbox/sdk/notifications)
* **Want to send notifications?** Check the [Send SDK documentation](/alerts/send/)

The `NotificationsButton` provides everything most applications need for user notifications with minimal setup. For advanced customization needs, consider the standalone [`Notifications`](/alerts/integrate-inbox/sdk/notifications) component.


# Setup & Configuration
Source: https://docs.dialect.to/alerts/integrate-inbox/sdk/setup-configuration

Get the Dialect React SDK installed and configured for notification inbox integration with React hooks support and Solana wallet integration

Get the Dialect React SDK installed and configured for notification inbox integration. This guide covers installation, client setup, authentication, and environment configuration for frontend applications.

## Prerequisites

Before using the inbox components, ensure you have completed:

* **App Registration**: Your app must be registered with Dialect ([registration guide](/alerts/setup/register-app))
* **React Environment**: React 16.8+ with hooks support
* **Wallet Integration**: Solana wallet adapter or custom wallet implementation

## Installation

Install the React UI package and blockchain-specific SDK for your needs:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    # React UI components (required)
    npm install @dialectlabs/react-ui

    # Blockchain SDK for Solana
    npm install @dialectlabs/react-sdk-blockchain-solana
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    # React UI components (required)
    yarn add @dialectlabs/react-ui

    # Blockchain SDK for Solana
    yarn add @dialectlabs/react-sdk-blockchain-solana
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    # React UI components (required)
    pnpm add @dialectlabs/react-ui

    # Blockchain SDK for Solana
    pnpm add @dialectlabs/react-sdk-blockchain-solana
    ```
  </Tab>
</Tabs>

## Basic SDK Setup

### Simple Integration

For most applications, this basic setup is sufficient:

```tsx theme={null}
"use client";

import "@dialectlabs/react-ui/index.css";
import { DialectSolanaSdk } from "@dialectlabs/react-sdk-blockchain-solana";
import { NotificationsButton } from "@dialectlabs/react-ui";

const DAPP_ADDRESS = "your-dapp-address";

export function App() {
  return (
    <div className="app">
      {/* Your app content */}
      
      <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
        <NotificationsButton />
      </DialectSolanaSdk>
    </div>
  );
}
```

### Custom Wallet Adapter

If you need to use a custom wallet implementation:

```tsx theme={null}
import { useMemo } from "react";
import { DialectSolanaSdk } from "@dialectlabs/react-sdk-blockchain-solana";
import { NotificationsButton } from "@dialectlabs/react-ui";
import { useMyCustomWallet } from "./my-wallet";

export function CustomWalletNotifications() {
  const wallet = useMyCustomWallet(); // Your wallet implementation

  const walletAdapter = useMemo(
    () => ({
      publicKey: wallet.publicKey, // PublicKey | null
      signMessage: wallet.signMessage, // (msg: Uint8Array) => Promise<Uint8Array>
      signTransaction: wallet.signTransaction, // <T extends Transaction | VersionedTransaction>(tx: T) => Promise<T>
    }),
    [wallet]
  );

  return (
    <DialectSolanaSdk
      dappAddress="your-dapp-address"
      customWalletAdapter={walletAdapter}
    >
      <NotificationsButton />
    </DialectSolanaSdk>
  );
}
```

### Environment Configuration

Configure your Dialect SDK wrapper to switch between production and development environments:

```tsx theme={null}
import { DialectSolanaSdk } from "@dialectlabs/react-sdk-blockchain-solana";

export function MyApp() {
  return (
    <DialectSolanaSdk 
      dappAddress={APP_ADDRESS}
      config={{
        environment: "development",
      }}
    >
      {/* Your notification components */}
    </DialectSolanaSdk>
  );
}
```

## Troubleshooting

**Styles not loading correctly:**

```tsx theme={null}
// ❌ Wrong - styles imported after component
import { NotificationsButton } from "@dialectlabs/react-ui";
import "@dialectlabs/react-ui/index.css";

// ✅ Correct - styles imported first
import "@dialectlabs/react-ui/index.css";
import { NotificationsButton } from "@dialectlabs/react-ui";
```

**dappAddress not found:**

* Ensure your app is registered with Dialect
* Verify the dappAddress matches your registration
* Check environment configuration (development vs production)

**Wallet connection issues:**

* Ensure wallet adapter is properly configured
* Check wallet adapter version compatibility
* Verify wallet permissions and connection state


# Universal Inbox 📥
Source: https://docs.dialect.to/alerts/integrate-inbox/universal-inbox

A shared, user-controlled, actionable communication layer across the entire Web3 ecosystem.

<img alt="Fully interoperable inboxes across Web3 applications" />

The Universal Inbox represents the next evolution of messaging, transforming isolated app notifications into a shared, user-controlled communication layer across the entire ecosystem.

## What is a Universal Inbox?

Traditionally, each application maintains its own dedicated inbox for users. When you use Drift, you receive Drift notifications. When you use Bonk, you get Bonk alerts. Each app operates in isolation, creating fragmented communication experiences.

The Universal Inbox breaks down these silos by creating a **shared notification feed** where users can opt-in to receive messages from multiple applications they care about. Instead of checking separate inboxes across different apps, users have one central place to see all their notifications.

## How It Works

The Universal Inbox builds directly on Dialect's existing notification infrastructure:

```mermaid theme={null}
graph TB
    subgraph "Subscribed Apps"
        App1[🚀 Jito<br/>MEV Rewards]
        App2[🐕 Bonk<br/>Community Updates] 
        App3[⚡ Sanctum<br/>Staking Rewards]
        App4[📊 Your App<br/>Custom Notifications]
    end
    
    App1 --> Inbox[📥 Universal Inbox]
    App2 --> Inbox
    App3 --> Inbox
    App4 --> Inbox
    
    Inbox --> User[👤 User]
```

### Core Concepts

**Cross-App Subscriptions**: Users can subscribe to notifications from any registered Dialect app, not just the one they're currently using. A user in your DeFi app could also receive liquidation alerts from Drift and governance updates from their favorite DAO.

**User-Controlled**: Users have complete control over which apps they want to hear from and through which channels (push, email, in-app).

**Shared Infrastructure**: All apps use the same Dialect messaging infrastructure, making cross-app communication seamless. The same APIs that power your app's notifications can deliver messages from any other registered app.

## Building on Existing Infrastructure

The Universal Inbox doesn't require new APIs or endpoints—it leverages the notification system you're already familiar with:

### App Discovery & Subscription

Users discover and subscribe to apps using the existing app management endpoints:

* **[GET /v2/apps](https://alerts-api.dial.to/docs#tag/subscriber/GET/v2/apps)**: Lists all available apps users can subscribe to
* **[POST /v2/subscribe](https://alerts-api.dial.to/docs#tag/subscriber/POST/v2/subscribe)**: Subscribe to notifications from specific apps
* **[POST /v2/unsubscribe](https://alerts-api.dial.to/docs#tag/subscriber/POST/v2/unsubscribe)**: Unsubscribe from app notifications

For implementation details, see the [User Management](/alerts/integrate-inbox/user-management) documentation.

### Unified Message History

The notification history endpoints automatically aggregate messages from all subscribed apps:

* **[GET /v2/history](https://alerts-api.dial.to/docs#tag/subscriber/GET/v2/history)**: Retrieves unified message history across all subscribed apps
* **[GET /v2/history/summary](https://alerts-api.dial.to/docs#tag/subscriber/GET/v2/history/summary)**: Gets unread counts and latest messages
* **[POST /v2/history/read](https://alerts-api.dial.to/docs#tag/subscriber/POST/v2/history/read)**: Marks messages as read

For implementation details, see the [Notifications](/alerts/integrate-inbox/api/notifications) documentation.

### Cross-Channel Delivery

Messages from all subscribed apps are delivered through the user's preferred channels:

* **Push Notifications**: Mobile alerts from any subscribed app
* **Email**: Emails from any subscribed app
* **In-App**: Unified notification feed within your application

For implementation details, see the [Push Notifications](/alerts/integrate-inbox/api/push-notifications) documentation.

## User Experience Benefits

### For Users

* **Single Source of Truth**: One inbox for all notifications instead of scattered app-specific feeds
* **Reduced Context Switching**: No need to check multiple apps for important updates
* **Granular Control**: Choose exactly which apps to hear from and how
* **Consistent Experience**: Familiar notification patterns across all apps

### For Developers

* **Increased Engagement**: Users can discover and engage with your app through the unified feed
* **Network Effects**: Benefit from the broader Dialect ecosystem of apps and users
* **Reduced Development**: Leverage existing notification infrastructure instead of building from scratch
* **Cross-App Integration**: Enable users to stay connected with your app even when using others

## Implementation Strategy

To support the Universal Inbox in your application:

### 1. App Registration

Ensure your app is properly registered with Dialect so users can discover and subscribe to it. See the [App Registration guide](/alerts/setup/register-app).

### 2. Request Universal Inbox Access

Universal Inbox requires manual activation for your project. **Contact us at [hello@dialect.to](mailto:hello@dialect.to)** to request access. Our team will review your request and activate the feature for your app.

### 3. User Authentication

Implement the authentication flow so users can manage their cross-app subscriptions. See the [Authentication documentation](/alerts/integrate-inbox/api/authentication).

### 4. Subscription Management

Build UI that allows users to:

* Browse available apps using the `/v2/apps` endpoint
* Subscribe/unsubscribe from apps they're interested in
* Manage notification preferences per app

### 5. Unified Inbox Display

Create a notification inbox that shows messages from all subscribed apps:

* Use `/v2/history` to fetch a unified message stream
* Display app branding/icons to show message sources
* Implement filtering options (by app, by type, etc.)

### 6. Cross-App Actions

Consider implementing actions that work across apps:

* "Subscribe to similar apps" recommendations
* Cross-app notification batching
* Unified notification settings

## Getting Started

Ready to support the Universal Inbox? Start with these resources:

1. **[Authentication](/alerts/integrate-inbox/api/authentication)** - Set up user authentication for subscription management
2. **[User Management](/alerts/integrate-inbox/user-management)** - Implement app discovery and subscription flows
3. **[Notifications](/alerts/integrate-inbox/api/notifications)** - Build the unified message feed
4. **[Push Notifications](/alerts/integrate-inbox/api/push-notifications)** - Enable cross-app mobile notifications

The Universal Inbox transforms Web3 from a collection of isolated apps into a connected ecosystem where users stay informed and engaged across their entire on-chain journey.


# User Management
Source: https://docs.dialect.to/alerts/integrate-inbox/user-management

Manage user subscriptions, notification preferences, channel configurations, and topic organization for your Dialect integration.

Manage user subscriptions, notification preferences, channel configurations, and topic organization. This section covers the complete user workflow from initial subscription to advanced notification management.

## Prerequisites

Before managing users, ensure you have completed these steps:

1. **App Registration**: Register your app with Dialect (see the [registration guide](/alerts/setup/register-app) if you need to set this up)

## User Management Workflow Overview

Dialect's user management follows a three-step process:

1. **User Subscription**: User subscribes to your app (via notification widget or SDK) and automatically gets IN\_APP notifications
2. **Channel Management**: User can add email and Telegram channels for additional notification delivery methods
3. **Topic Organization**: Configure notification categories and topics that users can selectively subscribe to

## Step 1: Subscription Management

Before a user can receive messages, they have to be subscribed to your service.

### Subscribe user

<Tabs>
  <Tab title="SDK">
    Create a subscription for a user's wallet address to your app. This automatically enables them to receive IN\_APP notifications.

    ```typescript theme={null}
    // Step 1: User subscribes to your app (gets IN_APP notifications automatically)
    const subscription = await dialectSolanaSdk.wallet.dappAddresses.create({
      addressId: address.id,
      enabled: true,
      dappPublicKey,
    });
    ```
  </Tab>

  <Tab title="Notification Components">
    <img alt="Subscribe to notifications using react notifications component" />

    Users subscribe by connecting their wallet and signing a message in the notification widget. This automatically enables IN\_APP notifications.
  </Tab>

  <Tab title="API">
    Subscribe a user to channels via API. You can specify which channels to subscribe to, or omit `channel` to subscribe to all available channels:

    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/subscribe \
      --request POST \
      --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
      --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "appId": "YOUR_APP_ID",
        "channel": ["IN_APP", "EMAIL"]
      }'
    ```

    * `appId`: Your application's unique identifier (optional if using client key)
    * `channel`: Channel or array of channels to subscribe to (`IN_APP`, `EMAIL`, `TELEGRAM`). If omitted, subscribes to all available channels
    * `Authorization`: Bearer token (see authentication section)
    * `X-Dialect-Client-Key`: Your client key

    The response will be an empty JSON object indicating success:

    ```json theme={null}
    {}
    ```
  </Tab>
</Tabs>

### Enabling & disabling a subscription

<Tabs>
  <Tab title="SDK">
    Enable/disable a subscription programmatically:

    ```typescript theme={null}
    const updatedSubscription = await dialectSolanaSdk.wallet.dappAddresses.update({
      dappAddressId: subscription.id,
      enabled: false,
    });
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can enable or disable notifications for your app in the notification widget's settings panel.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Not supported via public API.\
    Please use the Notification Components or SDK methods above.
  </Tab>
</Tabs>

### Getting subscriptions by id

<Tabs>
  <Tab title="SDK">
    Retrieve a specific subscription using its unique ID:

    ```typescript theme={null}
    const specificSubscription = await dialectSolanaSdk.wallet.dappAddresses.find({
      dappAddressId: subscription.id,
    });
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can view their current subscription status in the notification widget's settings panel.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Not supported via public API.\
    Please use the Notification Components or SDK methods above.
  </Tab>
</Tabs>

### Getting subscriptions by wallet

<Tabs>
  <Tab title="SDK">
    Retrieve all subscriptions for a wallet address:

    ```typescript theme={null}
    const allSubscriptions = await dialectSolanaSdk.wallet.dappAddresses.findAll({
      dappPublicKey, // optional parameter
      addressIds: [address.id], // optional parameter
    });
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can view all their subscriptions in the notification widget's settings panel.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Get detailed subscription information for the authenticated user:

    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/apps \
      --request GET \
      --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
      --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY'
    ```

    This returns comprehensive subscription details:

    ```json theme={null}
    {
      "apps": [
        {
          "id": "app-uuid",
          "name": "Your App Name",
          "subscribed": true,
          "channels": [
            { "channel": "IN_APP", "subscribed": true },
            { "channel": "EMAIL", "subscribed": false },
            { "channel": "TELEGRAM", "subscribed": true }
          ],
          "topics": [
            {
              "id": "topic-uuid",
              "name": "Price Alerts",
              "slug": "price-alerts",
              "subscribed": true
            }
          ]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

### Getting subscribers by app

<Tabs>
  <Tab title="SDK">
    Not available via SDK. Use the API method below for server-side subscriber management.
  </Tab>

  <Tab title="Notification Components">
    App owners can view subscriber counts and details through their admin dashboard, not through the notification widget.

    *Subscriber management is handled server-side.*
  </Tab>

  <Tab title="API">
    Get all subscribers for your app (app owner perspective):

    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/subscribers \
      --request GET \
      --header 'x-dialect-api-key: YOUR_API_KEY'
    ```

    * `appId`: Your application's unique identifier
    * `offset`: (Optional) Pagination offset (default: 0)
    * `limit`: (Optional) Pagination limit (default: 1000, max: 10000)

    Response contains all wallet addresses subscribed to your app:

    ```json theme={null}
    {
      "subscribers": [
        { "walletAddress": "6CxnSjtasq5Tzwb4b93AhLofXtiDvMpQ2vTkWdSZqTH7" },
        { "walletAddress": "AnotherWalletAddress..." }
      ]
    }
    ```
  </Tab>
</Tabs>

### Deleting a subscription

<Tabs>
  <Tab title="SDK">
    Remove a subscription completely:

    ```typescript theme={null}
    await dialectSolanaSdk.wallet.dappAddresses.delete({
      dappAddressId: subscription.id,
    });
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can unsubscribe from your app in the notification widget's settings panel.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Unsubscribe from an app or specific channels:

    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/unsubscribe \
      --request POST \
      --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
      --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "appId": "YOUR_APP_ID",
        "channel": ["IN_APP", "EMAIL", "TELEGRAM"]
      }'
    ```

    * `appId`: App ID or array of App IDs. If omitted, targets all apps available for the client
    * `channel`: Channel or array of channels to unsubscribe from. If omitted, unsubscribes from all channels

    To completely unsubscribe from an app, omit the `channel` parameter:

    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/unsubscribe \
      --request POST \
      --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
      --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "appId": "YOUR_APP_ID"
      }'
    ```
  </Tab>
</Tabs>

## Step 2: Channel Management

After subscribing to your app, users can add additional notification channels like email and Telegram. Users manage addresses via the Dialect data service, where they may add, verify, update & remove addresses for these various channels.

### Add User Email Address

<Tabs>
  <Tab title="SDK">
    Add an email address for a user to receive notifications via email. The address will need to be verified before notifications can be sent.

    ```typescript theme={null}
    // Step 2: User can add additional channels like email or Telegram
    const address = await dialectSolanaSdk.wallet.addresses.create({
      type: AddressType.Email,
      value: "address@mailservice.com",
    });
    ```
  </Tab>

  <Tab title="Notification Components">
    Users add and manage channels (email, Telegram) in the notification widget's settings screen. The component handles verification and management flows.

    ```tsx theme={null}
    <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
      <NotificationsButton />
    </DialectSolanaSdk>
    ```

    *In the settings panel, users can add, verify, and remove channels. No extra code needed!*
  </Tab>

  <Tab title="API">
    Not supported via public API.\
    Please use the Notification Components or SDK methods above.
  </Tab>
</Tabs>

### Verify an address

<Tabs>
  <Tab title="SDK">
    Dialect uses verification codes to verify ownership of web2 channels such as email and Telegram. These codes are sent to the address in question.

    ```typescript theme={null}
    // Verify address (email or telegram). Constraint: there are
    // 3 attempts to verify address, otherwise use call below to send new
    // verification code
    const verifiedAddress = await dialectSolanaSdk.wallet.addresses.verify({
      addressId: address.id,
      code: "1337",
    });
    ```

    If you did not receive the verification code, or if you failed to enter the correct value after several attempts, you can send a new code via the following call:

    ```typescript theme={null}
    // Resend verification code. Constraint: you must wait 60 sec before
    // resending the code.
    await dialectSolanaSdk.wallet.addresses.resendVerificationCode({
      addressId: address.id,
    });
    ```
  </Tab>

  <Tab title="Notification Components">
    Users verify their email/Telegram addresses in the notification widget's settings screen by entering the verification code sent to their address.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Not supported via public API.\
    Please use the Notification Components or SDK methods above.
  </Tab>
</Tabs>

### Get addresses owned by a wallet

<Tabs>
  <Tab title="SDK">
    Retrieve address information for a wallet. This shows all the notification channels (email, Telegram) that a user has configured.

    ```typescript theme={null}
    // Find all addresses owned by wallet
    const allAddresses = await dialectSolanaSdk.wallet.addresses.findAll();

    // Find specific address owned by wallet
    const specificAddress = await dialectSolanaSdk.wallet.addresses.find({
      addressId: address.id,
    });
    ```

    You can also check email subscription status using the hook:

    ```typescript theme={null}
    import { AddressType } from '@dialectlabs/sdk';
    import { useNotificationChannelDappSubscription } from '@dialectlabs/react-sdk';

    // Check email subscription status
    const {
      enabled: emailEnabled,
      isFetchingSubscriptions: emailFetching,
    } = useNotificationChannelDappSubscription({
      addressType: AddressType.Email,
      dappAddress: DAPP_ADDRESS,
    });

    if (!emailFetching) {
      console.log('Email subscribed:', emailEnabled);
    }
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can view all their configured notification channels in the notification widget's settings screen.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Get channel subscription status via the apps endpoint:

    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/apps \
      --request GET \
      --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
      --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY'
    ```

    This shows which channels are subscribed for each app:

    ```json theme={null}
    {
      "apps": [
        {
          "id": "app-uuid",
          "name": "Your App",
          "subscribed": true,
          "channels": [
            { "channel": "IN_APP", "subscribed": true },
            { "channel": "EMAIL", "subscribed": false },
            { "channel": "TELEGRAM", "subscribed": true }
          ]
        }
      ]
    }
    ```

    Note: This endpoint shows channel subscription status, but email/Telegram addresses must be managed via components or SDK.
  </Tab>
</Tabs>

### Subscribe to specific channels

<Tabs>
  <Tab title="SDK">
    Use the `useNotificationChannelDappSubscription` hook to manage email subscriptions:

    ```typescript theme={null}
    import { AddressType } from '@dialectlabs/sdk';
    import { useNotificationChannelDappSubscription } from '@dialectlabs/react-sdk';

    // Subscribe to email notifications for your dapp
    const {
      enabled: emailEnabled,
      isToggling: emailToggling,
      toggleSubscription: toggleEmailSubscription,
    } = useNotificationChannelDappSubscription({
      addressType: AddressType.Email,
      dappAddress: DAPP_ADDRESS,
    });

    // Enable email notifications
    await toggleEmailSubscription({ enabled: true });
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can enable/disable specific channels (email, Telegram) in the notification widget's settings screen.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Subscribe to specific channels for an app:

    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/subscribe \
      --request POST \
      --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
      --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "appId": "YOUR_APP_ID",
        "channel": ["EMAIL", "TELEGRAM"]
      }'
    ```

    Note: Email and Telegram channels require the user to have already added and verified those addresses via components or SDK.
  </Tab>
</Tabs>

### Unsubscribe from specific channels

<Tabs>
  <Tab title="SDK">
    Use the same `useNotificationChannelDappSubscription` hook to disable email notifications:

    ```typescript theme={null}
    import { AddressType } from '@dialectlabs/sdk';
    import { useNotificationChannelDappSubscription } from '@dialectlabs/react-sdk';

    const {
      enabled: emailEnabled,
      isToggling: emailToggling,
      toggleSubscription: toggleEmailSubscription,
    } = useNotificationChannelDappSubscription({
      addressType: AddressType.Email,
      dappAddress: DAPP_ADDRESS,
    });

    // Disable email notifications
    await toggleEmailSubscription({ enabled: false });

    // Check current subscription status
    console.log('Email notifications enabled:', emailEnabled);
    console.log('Currently toggling:', emailToggling);
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can disable specific channels in the notification widget's settings screen while keeping other channels active.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Unsubscribe from specific channels while maintaining subscription to others:

    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/unsubscribe \
      --request POST \
      --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
      --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "appId": "YOUR_APP_ID",
        "channel": ["EMAIL"]
      }'
    ```

    This will unsubscribe from EMAIL notifications while keeping IN\_APP and TELEGRAM active.
  </Tab>
</Tabs>

### Update an address

<Tabs>
  <Tab title="SDK">
    You can update an address at any time. All of your subscriptions will remain intact, but won't be sent until you re-verify.

    ```typescript theme={null}
    // Update address value
    const updatedAddress = await dialectSolanaSdk.wallet.addresses.update({
      addressId: address.id,
      value: "updated.address@example.com",
    });
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can update their email/Telegram addresses in the notification widget's settings screen.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Not supported via public API.\
    Please use the Notification Components or SDK methods above.
  </Tab>
</Tabs>

### Remove an address

<Tabs>
  <Tab title="SDK">
    You can delete an address at any time. This will remove all subscriptions associated with that address.

    ```typescript theme={null}
    // Delete address
    await dialectSolanaSdk.wallet.addresses.delete({
      addressId: address.id,
    });
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can remove email/Telegram addresses in the notification widget's settings screen.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Not supported via public API.\
    Please use the Notification Components or SDK methods above.
  </Tab>
</Tabs>

### Push Notifications

Push Notifications require a more complex setup and you can find a full walkthrough in the [API section](/alerts/integrate-inbox/api/push-notifications).

## Step 3: Topic Management

Create and manage notification topics to organize and categorize your app's notifications. Topics help users subscribe to specific types of alerts they care about.

### Create a new notification type

<Tabs>
  <Tab title="SDK">
    Define a new category of notifications for your app. Each notification type represents a specific kind of alert that users can subscribe to independently.

    ```typescript theme={null}
    // Create a new notification type
    const dapp = await dialectSolanaSdk.dapps.find();

    if (!dapp) {
      throw new IllegalStateError(
        "Dapp doesn't exist, please create dapp before using it"
      );
    }

    const notificationType = await dapp.notificationTypes.create({
      humanReadableId: "announcements",
      name: "Announcements",
      orderingPriority: 0,
      trigger: "Notification description or triggering event/conditions",
      defaultConfig: {
        enabled: true,
      },
    });
    ```
  </Tab>

  <Tab title="Notification Components">
    App owners create notification topics through their backend or admin interface, not through the notification widget.

    *Topics are created server-side and automatically appear in user widgets.*
  </Tab>

  <Tab title="API">
    Not supported via public API.\
    Please use the SDK method above.
  </Tab>
</Tabs>

### Update an existing notification type

<Tabs>
  <Tab title="SDK">
    Modify the properties of an existing notification type, such as changing its name or trigger description. This is useful when refining your notification categories.

    ```typescript theme={null}
    const allNotificationTypes = await dapp.notificationTypes.findAll();

    if (allNotificationTypes.length < 1) return;

    const notificationType = allNotificationTypes[0];

    const patched = await dapp.notificationTypes.patch(notificationType.id, {
      name: "New feature announcements",
    });
    ```
  </Tab>

  <Tab title="Notification Components">
    App owners update notification topics through their backend or admin interface, not through the notification widget.

    *Topic updates are managed server-side and automatically reflected in user widgets.*
  </Tab>

  <Tab title="API">
    Not supported via public API.\
    Please use the SDK method above.
  </Tab>
</Tabs>

### Get all topics

<Tabs>
  <Tab title="SDK">
    Retrieve all notification types (topics) for your app:

    ```typescript theme={null}
    const dapp = await dialectSolanaSdk.dapps.find();
    const allNotificationTypes = await dapp.notificationTypes.findAll();

    // Or find a specific topic by human-readable ID
    const specificTopic = await dapp.notificationTypes.find({ 
      humanReadableId: "price-alerts" 
    });
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can view all available topics for each app in the notification widget's settings screen.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Get all available topics for a user:

    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/topics?appId=YOUR_APP_ID \
      --request GET \
      --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
      --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY'
    ```

    This returns topics organized by app with subscription status:

    ```json theme={null}
    {
      "byApp": {
        "app-uuid": {
          "items": [
            {
              "id": "topic-uuid",
              "name": "Price Alerts",
              "description": "Receive alerts when prices drop",
              "slug": "price-alerts",
              "subscribed": true
            }
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Subscribe to topics

<Tabs>
  <Tab title="SDK">
    Use the `useNotificationSubscriptions` hook to manage topic subscriptions:

    ```typescript theme={null}
    import { useNotificationSubscriptions } from '@dialectlabs/react-sdk';

    const {
      subscriptions,
      update,
      isFetching,
      isUpdating,
    } = useNotificationSubscriptions({
      dappAddress: DAPP_ADDRESS,
    });

    // Subscribe to a specific topic
    const subscribeToTopic = async (topicId: string) => {
      await update({
        notificationTypeId: topicId,
        config: {
          enabled: true,
        },
      });
    };

    // Example: Subscribe to price alerts topic
    await subscribeToTopic('price-alerts-topic-id');
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can subscribe to topics directly in the notification widget's settings screen.\
    When a user toggles a topic on, the component handles the subscription automatically.

    ```tsx theme={null}
    <DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
      <NotificationsButton />
    </DialectSolanaSdk>
    ```

    *In the settings panel, users can toggle topics on/off. No extra code needed!*
  </Tab>

  <Tab title="API">
    Subscribe to a specific topic:

    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/topics/subscribe \
      --request POST \
      --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
      --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "topicId": "123e4567-e89b-12d3-a456-426614174000"
      }'
    ```
  </Tab>
</Tabs>

### Unsubscribe from topics

<Tabs>
  <Tab title="SDK">
    Use the same `useNotificationSubscriptions` hook to unsubscribe from topics:

    ```typescript theme={null}
    import { useNotificationSubscriptions } from '@dialectlabs/react-sdk';

    const {
      subscriptions,
      update,
      isUpdating,
    } = useNotificationSubscriptions({
      dappAddress: DAPP_ADDRESS,
    });

    // Unsubscribe from a specific topic
    const unsubscribeFromTopic = async (topicId: string) => {
      await update({
        notificationTypeId: topicId,
        config: {
          enabled: false,
        },
      });
    };

    // Example: Unsubscribe from price alerts topic
    await unsubscribeFromTopic('price-alerts-topic-id');
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can unsubscribe from topics directly in the notification widget's settings screen by toggling them off.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Unsubscribe from a specific topic:

    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/topics/unsubscribe \
      --request POST \
      --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
      --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "topicId": "123e4567-e89b-12d3-a456-426614174000"
      }'
    ```
  </Tab>
</Tabs>

### Get topic subscription status

<Tabs>
  <Tab title="SDK">
    Use the `useNotificationSubscriptions` hook to get topic subscription status:

    ```typescript theme={null}
    import { useNotificationSubscriptions } from '@dialectlabs/react-sdk';

    const {
      subscriptions,
      isFetching,
    } = useNotificationSubscriptions({
      dappAddress: DAPP_ADDRESS,
    });

    // Check if a specific topic is subscribed
    const isTopicSubscribed = (topicId: string) => {
      const subscription = subscriptions.find(
        (sub) => sub.notificationType.id === topicId
      );
      return subscription?.subscription?.config?.enabled || false;
    };

    // Get all subscribed topics
    const subscribedTopics = subscriptions.filter(
      (sub) => sub.subscription?.config?.enabled
    );

    if (!isFetching) {
      console.log('Price alerts subscribed:', isTopicSubscribed('price-alerts-topic-id'));
      console.log('All subscribed topics:', subscribedTopics);
    }
    ```
  </Tab>

  <Tab title="Notification Components">
    Users can view their topic subscription status in the notification widget's settings screen.

    *No extra code needed—handled by the component UI.*
  </Tab>

  <Tab title="API">
    Get topic subscription status via the apps endpoint:

    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/apps \
      --request GET \
      --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
      --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY'
    ```

    This returns apps with their topics and subscription status:

    ```json theme={null}
    {
      "apps": [
        {
          "id": "app-uuid",
          "name": "Your App",
          "subscribed": true,
          "topics": [
            {
              "id": "topic-uuid",
              "name": "Price Alerts",
              "slug": "price-alerts",
              "subscribed": true
            }
          ]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Best Practices

💡 **User Experience Tips**:

* Start users with a simple subscription, then let them add channels as needed
* Create meaningful notification types that users actually want to subscribe to
* Good topics are specific enough to be useful but broad enough to generate regular content
* Always respect user preferences and make unsubscribing easy

💡 **Technical Tips**:

* Always subscribe users to your app first using `dappAddresses.create()` before adding additional notification channels
* Implement proper error handling for address verification flows
* Use batch operations when managing multiple users to avoid rate limits

## Next Steps

Now that you understand user management concepts, you're ready to implement notification components:

1. **[NotificationsButton](/alerts/integrate-inbox/sdk/notifications-button)** - Complete done-for-you solution
2. **[Notifications](/alerts/integrate-inbox/sdk/notifications)** - Standalone component for custom integration

The components handle all the user management workflows described above, providing your users with intuitive interfaces for managing their notification preferences.


# Mobile Alert Stack
Source: https://docs.dialect.to/alerts/mobile-alerts/index

The complete mobile alerts stack for Web3 applications. Deliver alerts across any platform, in any programming language.

<img alt="Mobile Alert Stack - Cross-platform notifications for Web3 applications" />

## What is the Mobile Alert Stack?

The Mobile Alert Stack is a comprehensive suite of open APIs bundled with Firebase push notifications that extends Dialect's current alerts stack with cross-platform, cross-language capabilities. It's designed as parts of our product offering that get you ready for mobile—enabling Web3 applications to deliver notifications across mobile, web, email, and messaging platforms from a single integration.

Built from the ground up to support the same features as our existing Alert Stack, the Mobile Alert Stack now operates as a set of APIs that can be used cross-platform across React, Swift, Kotlin, React Native, and more to deliver the same experience directly inside your mobile app.

## Key Features

### Cross-Platform API Integration

Build with every programming language you want. Our open APIs enable notifications across any platform—Swift for iOS, Kotlin for Android, React Native for cross-platform mobile, or traditional web frameworks.

**What you get:**

<CardGroup>
  <Card title="Language Flexibility" icon="code">
    APIs that work with all programming languages
  </Card>

  <Card title="Platform Consistency" icon="mobile">
    Unified notification system across all platforms
  </Card>

  <Card title="Development Speed" icon="bolt">
    Get from nothing to your first alert integrated in 15 minutes
  </Card>

  <Card title="Complete Package" icon="box">
    All the tools you need to add mobile notifications to your application
  </Card>
</CardGroup>

### Firebase Push Notifications (Bundled)

Native mobile push notifications delivered through Firebase, bundled directly with the Mobile Alert Stack. We handle all the routing under the hood, including what users have subscribed for and what they haven't.

**Features:**

* **Native Integration**: Seamless integration with device notification systems
* **Automatic Routing**: Smart delivery based on user preferences and subscriptions
* **Rich Content**: Support for images, actions, and custom data
* **Cross-App Notifications**: Users can receive alerts from multiple apps they've subscribed to

### Multi-Channel Messaging

In-App, Email and Telegram are available as separate offerings, providing users choice in how they receive different types of alerts.

## Integration Paths

Choose your implementation approach:

<Tip>
  **Recommended approach:** Start with receiving integration first, then add sending capabilities to enable the full cross-app notification experience.
</Tip>

<AccordionGroup>
  <Accordion title="For Receiving Notifications" icon="inbox">
    Start with the [User Management](/alerts/integrate-inbox/user-management) guide and follow the [integration guide](/alerts/integrate-inbox/api/push-notifications) to:

    * Implement the [Universal Inbox](/alerts/integrate-inbox/universal-inbox) for cross-app notifications
    * Enable users to receive push notifications from multiple subscribed apps
    * Set up in-app notification feeds
  </Accordion>

  <Accordion title="For Sending Notifications" icon="paper-plane">
    Review the [sending guide](/alerts/send/api/push-notifications) to:

    * Set up Firebase for push notifications
    * Integrate Dialect's API for multi-channel delivery
    * Configure notification routing and user preferences
  </Accordion>
</AccordionGroup>

## Why Mobile Push Notifications?

Web3 is increasingly mobile-first, and users expect instant notifications for critical events like liquidation warnings, price alerts, governance proposals, and trading opportunities.

Push notifications offer unique advantages:

* **Instant Delivery**: Push notifications arrive immediately, even when apps aren't open
* **Native Experience**: Seamless integration with device notification systems
* **Higher Engagement**: Push notifications typically see 3-10x higher open rates than email
* **Privacy-First**: No need to share email addresses or join Telegram channels
* **Rich Content**: Support for images, actions, and custom data

## Cross-Platform Consistency

The same notification system powers all channels, ensuring consistent messaging and user experience whether users receive alerts via push, email, or in-app notifications.

Users can choose their preferred channels for different alert types:

| Alert Type                                   | 📱 Push | 📧 Email | 💬 Telegram | 📋 In-App |
| -------------------------------------------- | ------- | -------- | ----------- | --------- |
| **Critical alerts** (liquidations, security) | ✅       | ✅        | ✅           | ✅         |
| **Trading signals** (price alerts)           | ✅       | ❌        | ❌           | ✅         |
| **Daily summaries** (portfolio updates)      | ❌       | ✅        | ✅           | ❌         |
| **Governance proposals** (voting deadlines)  | ❌       | ✅        | ✅           | ✅         |
| **Transaction confirmations** (swaps, sends) | ✅       | ❌        | ❌           | ✅         |

This approach ensures your users never miss important information, regardless of their preferred communication method or device.

## Real-World Example: Jupiter Mobile Radar

[Jupiter Exchange announced](https://x.com/JupiterExchange/status/1935683989894758759) native push notification support powered by Dialect, bringing real-time alerts directly to users' phones.

<img alt="Jupiter Mobile app showcasing real-time push notifications and alerts" />

<CardGroup>
  <Card title="Transaction Alerts" icon="credit-card">
    Push notifications for swaps, sends, and receives
  </Card>

  <Card title="Community Updates" icon="megaphone">
    High-fidelity channel for product and company announcements
  </Card>

  <Card title="In-App Feed" icon="list">
    Same amazing alert experience directly in the mobile app
  </Card>

  <Card title="Lock Screen Notifications" icon="mobile">
    Direct delivery to users' phones
  </Card>
</CardGroup>


# Quick Start
Source: https://docs.dialect.to/alerts/quick-start

Get your first notification working in under 15 minutes. Complete flow from dashboard registration to sending your first notification.

## Prerequisites

<Info>
  **Before you start, make sure you have:**

  * **Solana Wallet**: Any Solana wallet (Phantom, Solflare, etc.)
  * **Development Environment**: Node.js 16+ installed
  * **Basic Knowledge**: React components and wallet connections
</Info>

## Video Tutorial

Watch the complete walkthrough to see exactly how it works.

<iframe title="YouTube video player" />

### Chapters

* [00:00](https://youtu.be/aPLaXqEkzJY?t=0) Send your first alert in 15 minutes
* [00:25](https://youtu.be/aPLaXqEkzJY?t=25) Prerequisites
* [03:13](https://youtu.be/aPLaXqEkzJY?t=193) Register your app
* [05:37](https://youtu.be/aPLaXqEkzJY?t=337) Setup a clean project
* [07:36](https://youtu.be/aPLaXqEkzJY?t=456) Implementation
* [13:38](https://youtu.be/aPLaXqEkzJY?t=818) Signup for messages
* [14:55](https://youtu.be/aPLaXqEkzJY?t=895) Send message to a wallet

## What You'll Build

By the end of this tutorial, you'll have:

* ✅ A working notification bell in your React app
* ✅ Users can subscribe to receive notifications
* ✅ Dashboard to compose and send notifications
* ✅ Your first notification successfully delivered

**Time Required**: \~15 minutes

## Step 1: Register Your App (3 minutes)

### Create a New Wallet

<Warning>
  Create a dedicated wallet for your app registration. This keeps your app's identity separate from your personal wallet and provides better security.
</Warning>

**In your Solana wallet app:**

1. **Create a new wallet** (most wallet apps have an "Add Wallet" or "+" option)
2. **Name it** something like "My App Notifications"
3. **Copy the wallet address** - you'll need this for registration

### Connect and Register

<video alt="Walkthrough of registering your project on the Dialect dashboard" />

1. **Visit**: [https://dashboard.dialect.to/](https://dashboard.dialect.to)
2. **Click**: "Alerts" in the left sidebar
3. **Click**: "Guide" tab (don't get confused by "Compose")
4. **Connect**: Your **new** wallet (not your main wallet)
5. **Sign**: The message to authenticate

### Complete Registration

Fill out your app information:

* **Project Logo**: Upload your app's logo
* **Project Name**: Your application name
* **Description**: Brief description of your app

Click **"Register"** and wait for the ✅ confirmation.

### Save Your App Address

**Important**: Copy your app address from the bottom-left corner (click "Copy Address"). This should match the public key of the wallet you just created.

```bash theme={null}
# This is your app's public key - save it!
dappAddress=5XCdQVqopjAoVkNhkXWHmeHNhRS5bPiATUULy8FHDySX
```

**Note**: This address will be used to initialize the Dialect SDK in your React component (Step 3).

## Step 2: Set Up Your Project (3 minutes)

<Tip>
  If you already have an existing React/Next.js project, you can skip this step and jump directly to [Step 3: Add Notification Bell](#step-3-add-notification-bell-4-minutes). The notification bell works with any React application.
</Tip>

### Clone the Scaffold

We'll start with a fresh project using the Solana app scaffold:

```bash theme={null}
# Create a new Solana dApp scaffold
npx create-solana-dapp@latest alerts-tutorial

# Choose your options when prompted:
# - Framework: Next.js (A React framework by Vercel)
# - Template: gill-next-tailwind (Next.js, Tailwind, gill based on @solana/kit, Wallet UI)

# Navigate to the project
cd alerts-tutorial

# Start development server
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) to verify your scaffold is running correctly.

## Step 3: Add Notification Bell (4 minutes)

### Install Dialect Packages

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @dialectlabs/react-ui @dialectlabs/react-sdk-blockchain-solana
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @dialectlabs/react-ui @dialectlabs/react-sdk-blockchain-solana
    ```
  </Tab>
</Tabs>

### Create Notification Component

Create a new file `src/components/DialectNotificationComponent.tsx`:

```tsx title="src/components/DialectNotificationComponent.tsx" theme={null}
"use client";

import "@dialectlabs/react-ui/index.css";
import { DialectSolanaSdk } from "@dialectlabs/react-sdk-blockchain-solana";
import { NotificationsButton } from "@dialectlabs/react-ui";

// Replace with your actual app address from Step 1
const dappAddress = "5XCdQVqopjAoVkNhkXWHmeHNhRS5bPiATUULy8FHDySX";

export const DialectNotificationComponent = () => {
  return (
    <DialectSolanaSdk
      dappAddress={dappAddress}
      config={{
        environment: "production",
      }}
    >
      <NotificationsButton />
    </DialectSolanaSdk>
  );
};

```

### Add to Your App Header

Add the notification bell to your app's header next to the wallet button.

Find the header file `src/components/app-header.tsx` and add the notification component:

```tsx title="src/components/app-header.tsx" theme={null}
// Add this import at the top with the other imports
import { DialectNotificationComponent } from "@/components/DialectNotificationComponent";

// Find the section with the wallet and other buttons, then add the component:
<div className="hidden md:flex items-center gap-4">
  <DialectNotificationComponent />
  <WalletButton />
  <ClusterButton />
  <ThemeSelect />
</div>
```

### Test the Component

<img alt="Screenshot highlighting Alert Bell icon in Navigation Bar incl. Modal" />

Refresh your browser and you should see the notification bell next to your wallet button and cluster selector in the top navigation.

## Step 4: User Subscribes to Notifications (2 minutes)

<video alt="Walkthrough of subscribing to notification topics and channels" />

In the next step, your users need to opt-in into notifications:

### Subscribe Process

1. **Connect Wallet**: User connects their wallet to your app
2. **Click Bell**: User clicks the notification bell
3. **Set Up Notifications**: Click "Set up notifications"
4. **Enable Notifications**: Make sure the toggle is "ON" (very important!)
5. **Choose Additional Channels**:
   * 📧 **Email**: User can optionally add their email
   * 📱 **Telegram**: User can optionally add their Telegram handle

## Step 5: Send Your First Notification (3 minutes)

<video alt="Walkthrough of sending your first alert via the dashboard" />

Now send a notification using the dashboard:

### Using the Dashboard

1. **Go back to**: [https://dashboard.dialect.to](https://dashboard.dialect.to)
2. **Click**: "Compose" tab
3. **You'll see**: "1 subscriber" (the user who just signed up)
4. **Write your message**:
   * **Title**: "🎉 Welcome to My App!"
   * **Body**: "This is your first notification from \[Your App Name]"
5. **Click**: "Send"

### Verify It Works

<img alt="Notification received via React UI component" />

Go back to your app or our [Alerts Example App](https://alerts-example.dialect.to) and:

* The notification bell should show a green dot (unread notification)
* Click the bell to see your message: "Welcome to My App!"
* The message shows "This is your first notification..."

**🎉 Congratulations! You've sent your first notification!**

## Troubleshooting

### ❌ "No subscribers found"

* Make sure the user clicked the bell and enabled notifications
* **Very important**: Check that the toggle is "ON" in the notification settings (sometimes it defaults to "OFF")

### ❌ "Component not rendering"

* Ensure you imported the CSS: `import "@dialectlabs/react-ui/index.css"`
* Check that your app address is correct
* Verify wallet connection is working

### ❌ "User not receiving notifications"

* User must connect wallet and enable notifications first
* Check dashboard analytics to see delivery status
* Verify the target wallet address is correct

## Customization

Want to customize the look and feel of your notification bell? Check out our **[Event Detection and Monitoring](/alerts/alerts-and-monitoring/index)** guide where you can see how companies like Tensor have customized the notification widget to match their brand.

You'll find detailed styling options including:

* Custom colors and themes
* Component styling with CSS
* Complete customization examples

## Learn More

* **[Sending Guide](/alerts/send/index)** - Send alerts to your users either programmatic or by using or no-code Dashboard
* **[Universal Inbox Guide](/alerts/integrate-inbox/index)** - Integrate an Inbox using APIs or advanced UI components
* **[Event Detection and Monitoring](/alerts/alerts-and-monitoring/index)**: Use events to send notifications to your users
* **[API Guide](/api-reference/send-alerts/send-alert)** - Get an overview of available API endpoints

**🎉 You're all set!** You now have notifications working in your app. Your users can receive important updates directly in their wallets, and you can reach them programmatically from your backend.


# Authentication
Source: https://docs.dialect.to/alerts/send/api/authentication

Authenticate with Dialect's REST API using your API key for server-side notification sending

## Getting Your API Key

To send notifications, you'll need to authenticate as an application using your API key. If you don't have your key yet, please contact us at [hello@dialect.to](mailto:hello@dialect.to).

## Using Your API Key

Include your API key in the `x-dialect-api-key` header for all server-side requests:

```typescript theme={null}
const response = await fetch(`https://alerts-api.dial.to/v2/${appId}/subscribers`, {
  method: 'GET',
  headers: {
    'x-dialect-api-key': 'YOUR_API_KEY'
  }
});

const { subscribers } = await response.json();
```

## Error Handling

### Common Authentication Errors

**401 Unauthorized**: Invalid or missing API key

```json theme={null}
{
  "error": "Unauthorized"
}
```

**403 Forbidden**: Valid API key but insufficient permissions

```json theme={null}
{
  "error": "Forbidden"
}
```

### Error Handling Example

```typescript theme={null}
async function sendNotificationSafely(appId: string, apiKey: string, message: any) {
  try {
    const response = await fetch(`https://alerts-api.dial.to/v2/${appId}/send`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(message)
    });

    if (!response.ok) {
      const error = await response.json();
      
      switch (response.status) {
        case 401:
          throw new Error('Invalid API key. Please check your credentials.');
        case 403:
          throw new Error('Access denied. Check your app permissions.');
        default:
          throw new Error(`HTTP ${response.status}: ${JSON.stringify(error)}`);
      }
    }

    return response.json();
  } catch (error) {
    console.error('Failed to send notification:', error);
    throw error;
  }
}
```

## Best Practices

💡 **Security**:

* Store API keys securely (environment variables, secrets management)
* Never expose API keys in client-side code
* Use HTTPS for all API communication

💡 **Error Handling**:

* Always check response status codes
* Implement proper retry logic for transient failures
* Log authentication errors for debugging

💡 **Rate Limiting**:

* Respect API rate limits to avoid being blocked
* Implement exponential backoff for retries


# Send alerts via API
Source: https://docs.dialect.to/alerts/send/api/index

Send alerts directly from your backend using Dialect's REST API with maximum flexibility across any programming language

## Why Use the REST API?

### Use-Cases

* Non-TypeScript/JavaScript applications
* Microservices architectures
* Custom integration requirements
* Teams preferring direct HTTP calls
* Maximum control over request/response handling

### Key capabilities

* Send to individual users or broadcast to all subscribers
* Support for all channels: EMAIL, TELEGRAM, IN\_APP, PUSH
* Batch operations for high-volume notifications

## Implementation Guide

1. **[Authentication](/alerts/send/api/authentication)**: Set up API keys for sending notifications from your backend.
2. **[Send Messages](/alerts/send/api/send-messages)**: Learn to send notifications using the core `/send` and `/send-batch` endpoints with examples for all channels.
3. **[Push Notifications](/alerts/send/api/push-notifications)**: Complete guide to mobile push notifications including Firebase setup, sending, and handling in your mobile apps.


# Push Notifications
Source: https://docs.dialect.to/alerts/send/api/push-notifications

Send mobile push notifications by adding PUSH to your channels array to reach users instantly on their mobile devices

<Warning>
  Please note that you can only send push notifications, once you've completed the registration process for your app as mentioned in the [Push Notifications Prerequisites](/alerts/integrate-inbox/api/push-notifications#prerequisites) section.
</Warning>

## How to Send Push

Simply include `PUSH` in your channels array:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/send \
      --request POST \
      --header 'x-dialect-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "recipient": {
          "type": "subscriber",
          "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
        },
        "channels": ["PUSH", "IN_APP"],
        "message": {
          "title": "Trade Executed! 📈",
          "body": "Your buy order for 10 SOL has been executed at $142.50"
        }
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const notification = {
      recipient: {
        type: 'subscriber',
        walletAddress: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'
      },
      channels: ['PUSH', 'IN_APP'],
      message: {
        title: 'Trade Executed! 📈',
        body: 'Your buy order for 10 SOL has been executed at $142.50'
      }
    };

    await fetch(`https://alerts-api.dial.to/v2/${appId}/send`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(notification)
    });
    ```
  </Tab>
</Tabs>

## Adding Custom Data

Include custom data for your app to handle deep linking or specific actions:

```typescript theme={null}
const pushWithData = {
  recipient: {
    type: 'subscriber',
    walletAddress: 'USER_WALLET_ADDRESS'
  },
  channels: ['PUSH'],
  message: {
    title: 'Price Alert! 🚨',
    body: 'SOL reached your target price of $150'
  },
  data: {
    action: 'price_alert',
    symbol: 'SOL',
    price: '150.00',
    alertId: 'alert_123'
  }
};
```

## Push Channel Ownership

**If you own the push channel** (have your own Firebase/FCM setup):

* You can send push notifications directly using `PUSH` in channels
* Consider mirroring `IN_APP` channel to see interesting push notifications from other projects that you might want to push to your users

**If you're a project without push channel ownership**:

* You cannot directly use the `PUSH` channel
* This is because push notifications require Firebase Cloud Messaging (FCM) integration and device token management
* Users need to have your specific mobile app installed and configured to receive your push notifications

## Complete Push Implementation

For full push notification setup including Firebase configuration, mobile app integration, user subscription management, and message handling, see:

**[Push Notifications in Inbox Integration →](/alerts/integrate-inbox/api/push-notifications)**


# Send Messages
Source: https://docs.dialect.to/alerts/send/api/send-messages

Send notifications to your users through various channels using the Dialect REST API, covering basic messaging to advanced features like batch operations and rich content

<Warning>
  **Users must subscribe to your app before you can send them notifications.** If you try to send a message to an unsubscribed user, it will not be delivered.

  **Setting up user subscriptions:** See our **[User Management guide](/alerts/integrate-inbox/user-management)** for implementation details.
</Warning>

## Prerequisites

Before sending messages, ensure you have completed these steps:

1. **Authentication Setup**: Have your API key ready (see the [Authentication guide](/alerts/send/api/authentication) if you need to set this up)
2. **App Registration**: Your app must be [registered](/alerts/setup/register-app) with Dialect
3. **User Subscriptions**: Ensure your users have [subscribed](/alerts/integrate-inbox/user-management) to receive notifications from your app

## Message Delivery Overview

Dialect's REST API provides flexible delivery options:

1. **Channel Selection**: Messages are sent according to user channel preferences (IN\_APP, email, Telegram, push)
2. **User Targeting**: Send to individual users, groups, or broadcast to all subscribers
3. **Rich Content**: Support for titles, actions, images, and formatted content
4. **Topic-Based**: Optional targeting based on notification types/topics

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Server as Your Server
    participant Dialect as Dialect API
    participant User as User's Device

    Server->>Dialect: 1. POST /v2/{appId}/send
    Note over Server,Dialect: API Key + recipient + message
    Dialect-->>Server: 2. Return 202 Accepted
    Note over Server,Dialect: Empty JSON response {}

    Dialect->>User: 3. Deliver notification
    Note over Dialect,User: Email, Telegram, IN_APP, Push
```

## Step 1: Basic Message Sending

### Send to a Single User

Send a notification to a specific user's wallet address. This is the most common messaging pattern.

**API Reference:** [`POST /v2/{appId}/send`](https://alerts-api.dial.to/docs#tag/Application/POST/v2/%7BappId%7D/send)

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/send \
      --request POST \
      --header 'x-dialect-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "recipient": {
          "type": "subscriber",
          "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
        },
        "channels": ["EMAIL", "IN_APP"],
        "message": {
          "title": "Welcome to Our Platform! 🎉",
          "body": "Thanks for joining us. Get started by exploring our features."
        }
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const message = {
      recipient: {
        type: 'subscriber',
        walletAddress: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'
      },
      channels: ['EMAIL', 'IN_APP'],
      message: {
        title: 'Welcome to Our Platform! 🎉',
        body: 'Thanks for joining us. Get started by exploring our features.'
      }
    };

    const response = await fetch(`https://alerts-api.dial.to/v2/${appId}/send`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(message)
    });

    const result = await response.json();
    ```
  </Tab>
</Tabs>

### Send to Multiple Users

Send the same notification to multiple specific users in a single request. This is more efficient than making individual API calls and supports up to 10,000 wallet addresses.

**API Reference:** [`POST /v2/{appId}/send`](https://alerts-api.dial.to/docs#tag/Application/POST/v2/%7BappId%7D/send)

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/send \
      --request POST \
      --header 'x-dialect-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "recipient": {
          "type": "subscribers",
          "walletAddresses": [
            "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
            "AnotherWalletAddress123...",
            "ThirdWalletAddress456..."
          ]
        },
        "channels": ["EMAIL", "IN_APP"],
        "message": {
          "title": "Welcome to Our Platform! 🎉",
          "body": "Thanks for joining us. Get started by exploring our features."
        }
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const users = [
      '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
      'AnotherWalletAddress123...',
      'ThirdWalletAddress456...'
    ];

    const multipleUsersMessage = {
      recipient: {
        type: 'subscribers',
        walletAddresses: users
      },
      channels: ['EMAIL', 'IN_APP'],
      message: {
        title: 'Welcome to Our Platform! 🎉',
        body: 'Thanks for joining us. Get started by exploring our features.'
      }
    };

    const response = await fetch(`https://alerts-api.dial.to/v2/${appId}/send`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(multipleUsersMessage)
    });
    ```
  </Tab>
</Tabs>

### Broadcast to All Users

Send notifications to all users subscribed to your app by using the `all-subscribers` recipient type.

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/send \
      --request POST \
      --header 'x-dialect-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "recipient": {
          "type": "all-subscribers"
        },
        "channels": ["EMAIL", "IN_APP"],
        "message": {
          "title": "Major Update Released! 🚀",
          "body": "Version 2.0 is now live with exciting new features."
        }
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const broadcastMessage = {
      recipient: {
        type: 'all-subscribers'
      },
      channels: ['EMAIL', 'IN_APP'],
      message: {
        title: 'Major Update Released! 🚀',
        body: 'Version 2.0 is now live with exciting new features.'
      }
    };

    const response = await fetch(`https://alerts-api.dial.to/v2/${appId}/send`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(broadcastMessage)
    });
    ```
  </Tab>
</Tabs>

### Send Personalized Messages to Multiple Users

Send **different** notification content to multiple users using the batch endpoint. This is ideal for personalized alerts like individual portfolio updates, transaction confirmations, or customized recommendations. Supports up to 500 personalized messages per batch.

**API Reference:** [`POST /v2/{appId}/send-batch`](https://alerts-api.dial.to/docs#tag/Application/POST/v2/%7BappId%7D/send-batch)

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/send-batch \
      --request POST \
      --header 'x-dialect-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "alerts": [
          {
            "recipient": {
              "type": "subscriber",
              "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
            },
            "channels": ["EMAIL", "IN_APP"],
            "message": {
              "title": "Your SOL Staking Rewards: 0.15 SOL Earned! 🎯",
              "body": "Great news! Your staked SOL has earned 0.15 SOL in rewards this week. Your total staked amount is now 12.5 SOL with an APY of 6.8%."
            }
          },
          {
            "recipient": {
              "type": "subscriber",
              "walletAddress": "AnotherWalletAddress123..."
            },
            "channels": ["EMAIL", "IN_APP"],
            "message": {
              "title": "Your USDC Position is Up 2.3% Today! 📈",
              "body": "Your USDC lending position has gained $45.80 today. Current balance: $2,045.80. Consider increasing your position while rates are favorable."
            }
          },
          {
            "recipient": {
              "type": "subscriber",
              "walletAddress": "ThirdWalletAddress456..."
            },
            "channels": ["EMAIL", "IN_APP"],
            "message": {
              "title": "Portfolio Weekly Summary: +$450 Gain 🚀",
              "body": "Your portfolio performed excellently this week with a total gain of $450 (12.3%). Top performer: Jupiter (JUP) +34%. Review your full analysis."
            }
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    // Example: Portfolio performance alerts with personalized data
    const portfolioAlerts = [
      {
        walletAddress: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
        rewards: 0.15,
        totalStaked: 12.5,
        apy: 6.8
      },
      {
        walletAddress: 'AnotherWalletAddress123...',
        usdcGain: 45.80,
        currentBalance: 2045.80,
        assetType: 'USDC Lending'
      },
      {
        walletAddress: 'ThirdWalletAddress456...',
        weeklyGain: 450,
        gainPercentage: 12.3,
        topPerformer: 'Jupiter (JUP)',
        topPerformance: 34
      }
    ];

    const batchPersonalizedAlerts = {
      alerts: portfolioAlerts.map(user => ({
        recipient: {
          type: 'subscriber',
          walletAddress: user.walletAddress
        },
        channels: ['EMAIL', 'IN_APP'],
        message: {
          title: user.rewards 
            ? `Your SOL Staking Rewards: ${user.rewards} SOL Earned! 🎯`
            : user.usdcGain 
            ? `Your ${user.assetType} is Up ${((user.usdcGain / (user.currentBalance - user.usdcGain)) * 100).toFixed(1)}% Today! 📈`
            : `Portfolio Weekly Summary: +$${user.weeklyGain} Gain 🚀`,
          
          body: user.rewards
            ? `Great news! Your staked SOL has earned ${user.rewards} SOL in rewards this week. Your total staked amount is now ${user.totalStaked} SOL with an APY of ${user.apy}%.`
            : user.usdcGain
            ? `Your ${user.assetType} position has gained $${user.usdcGain} today. Current balance: $${user.currentBalance}. Consider increasing your position while rates are favorable.`
            : `Your portfolio performed excellently this week with a total gain of $${user.weeklyGain} (${user.gainPercentage}%). Top performer: ${user.topPerformer} +${user.topPerformance}%. Review your full analysis.`
        }
      }))
    };

    const response = await fetch(`https://alerts-api.dial.to/v2/${appId}/send-batch`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(batchPersonalizedAlerts)
    });
    ```
  </Tab>
</Tabs>

<Note>
  **When to use send-batch vs send:**

  * **Use `/send` with `"subscribers"` type** when sending the **same message** to multiple users (up to 10,000)
  * **Use `/send-batch`** when sending **different personalized content** to multiple users (up to 500)
</Note>

## Step 2: Channel-Specific Delivery

### Target Email and Telegram

Control which channels receive your message by specifying the `channels` array. Note that IN\_APP notifications are delivered automatically when included, so you can add other channels as needed.

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/send \
      --request POST \
      --header 'x-dialect-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "recipient": {
          "type": "subscriber",
          "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
        },
        "channels": ["EMAIL", "TELEGRAM"],
        "message": {
          "title": "Weekly Portfolio Summary",
          "body": "Here is your portfolio performance for this week..."
        }
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const weeklyUpdate = {
      recipient: {
        type: 'subscriber',
        walletAddress: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'
      },
      channels: ['EMAIL', 'TELEGRAM'],
      message: {
        title: 'Weekly Portfolio Summary',
        body: 'Here is your portfolio performance for this week...'
      }
    };

    await fetch(`https://alerts-api.dial.to/v2/${appId}/send`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(weeklyUpdate)
    });
    ```
  </Tab>
</Tabs>

### Rich HTML Content for Email

When sending to email channels, you can use HTML formatting for rich content presentation.

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/send \
      --request POST \
      --header 'x-dialect-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "recipient": {
          "type": "subscriber",
          "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
        },
        "channels": ["EMAIL"],
        "message": {
          "title": "Transaction Confirmation - Order #12345",
          "body": "<h2>Transaction Successful</h2><p>Your transaction has been processed successfully.</p><table style=\"width: 100%; border-collapse: collapse;\"><tr><td style=\"padding: 10px; border: 1px solid #ddd;\"><strong>Amount:</strong></td><td style=\"padding: 10px; border: 1px solid #ddd;\">0.5 SOL</td></tr><tr><td style=\"padding: 10px; border: 1px solid #ddd;\"><strong>Fee:</strong></td><td style=\"padding: 10px; border: 1px solid #ddd;\">0.0025 SOL</td></tr><tr><td style=\"padding: 10px; border: 1px solid #ddd;\"><strong>Transaction ID:</strong></td><td style=\"padding: 10px; border: 1px solid #ddd;\">3x7Kj...9mNp</td></tr></table><p>View full details in your dashboard.</p>"
        }
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const emailNotification = {
      recipient: {
        type: 'subscriber',
        walletAddress: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'
      },
      channels: ['EMAIL'],
      message: {
        title: 'Transaction Confirmation - Order #12345',
        body: `
          <h2>Transaction Successful</h2>
          <p>Your transaction has been processed successfully.</p>
          
          <table style="width: 100%; border-collapse: collapse;">
            <tr>
              <td style="padding: 10px; border: 1px solid #ddd;"><strong>Amount:</strong></td>
              <td style="padding: 10px; border: 1px solid #ddd;">0.5 SOL</td>
            </tr>
            <tr>
              <td style="padding: 10px; border: 1px solid #ddd;"><strong>Fee:</strong></td>
              <td style="padding: 10px; border: 1px solid #ddd;">0.0025 SOL</td>
            </tr>
            <tr>
              <td style="padding: 10px; border: 1px solid #ddd;"><strong>Transaction ID:</strong></td>
              <td style="padding: 10px; border: 1px solid #ddd;">3x7Kj...9mNp</td>
            </tr>
          </table>
          
          <p>View full details in your dashboard.</p>
        `
      }
    };

    await fetch(`https://alerts-api.dial.to/v2/${appId}/send`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(emailNotification)
    });
    ```
  </Tab>
</Tabs>

## Step 3: Interactive & Rich Messages

### Actionable Notifications

Add action buttons to your notifications that allow users to take immediate action. Supports up to 3 action buttons that can direct users to external websites or blink-enabled actions.

When Dialect's [mapping service](/alerts/blinks-in-alerts#mapping-service) detects a supported protocol URL, it automatically enriches the alert with a  `context` object.

<Tabs>
  <Tab title="External Link">
    ```bash {14-18} theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/send \
      --request POST \
      --header 'x-dialect-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "recipient": {
          "type": "subscriber",
          "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
        },
        "channels": ["EMAIL", "IN_APP"],
        "message": {
          "title": "Staking Rewards Ready! 🎯",
          "body": "You have earned 0.15 SOL in staking rewards. Click below to claim them.",
          "actions": [{
            "type": "link",
            "label": "Claim Rewards",
            "url": "https://yourapp.com/claim-rewards"
          }]
        }
      }'
    ```
  </Tab>

  <Tab title="Blink Action">
    The highlighted line shows the supported protocol URL:

    ```bash {17} theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/send \
      --request POST \
      --header 'x-dialect-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "recipient": {
          "type": "subscriber",
          "walletAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176"
        },
        "channels": ["IN_APP"],
        "message": {
          "title": "Liquidation Warning",
          "body": "Your SOL/USDC position is at 78% LTV, approaching liquidation threshold of 80%.",
          "actions": [{
            "type": "link",
            "label": "Add Collateral",
            "url": "https://jup.ag/lend/borrow/1/nfts/2433"
          }]
        }
      }'
    ```

    When a supported URL is detected, the client receives the enriched alert with `context` in an action object:

    ```json {6-10} theme={null}
    {
      "actions": [{
        "type": "link",
        "label": "Add Collateral",
        "url": "https://jup.ag/lend/borrow/1/nfts/2433",
        "context": {
          "type": "position",
          "apiUrl": "https://markets.dial.to/api/v0/positions/owners?walletAddresses=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176&bundleIds=jupiter.borrow.1.2433",
          "action": "deposit"
        }
      }]
    }
    ```

    <Note>
      The `context` object is automatically added by Dialect's mapping service for supported protocols. See [Blinks in Alerts](/alerts/blinks-in-alerts) for complete implementation guide.
    </Note>
  </Tab>
</Tabs>

### Messages with Images

Include images in your notifications using publicly accessible URLs. Images are supported for IN\_APP and EMAIL channels.

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/send \
      --request POST \
      --header 'x-dialect-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "recipient": {
          "type": "all-subscribers"
        },
        "channels": ["IN_APP", "EMAIL"],
        "message": {
          "title": "New Feature Announcement 🎉",
          "body": "Check out our latest feature that will revolutionize your workflow!",
          "image": "https://yourapp.com/images/feature-preview.png",
          "actions": [
            {
              "type": "link",
              "label": "Try New Feature",
              "url": "https://yourapp.com/new-feature"
            }
          ]
        }
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const featureAnnouncement = {
      recipient: {
        type: 'all-subscribers'
      },
      channels: ['IN_APP', 'EMAIL'],
      message: {
        title: 'New Feature Announcement 🎉',
        body: 'Check out our latest feature that will revolutionize your workflow!',
        image: 'https://yourapp.com/images/feature-preview.png',
        actions: [
          {
            type: 'link',
            label: 'Try New Feature',
            url: 'https://yourapp.com/new-feature'
          }
        ]
      }
    };

    await fetch(`https://alerts-api.dial.to/v2/${appId}/send`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(featureAnnouncement)
    });
    ```
  </Tab>
</Tabs>

## Step 4: Custom Data

The `data` parameter allows you to attach arbitrary key-value pairs to your alerts. This data is accessible in notification history and push notification payloads, enabling powerful use cases.

**Common use cases:**

* Deep linking to specific screens in your app
* Transaction metadata for user reference
* Custom actions and routing logic
* Analytics and tracking identifiers

**Validation rules:**

* Property names: alphanumeric characters, underscores, and hyphens only (max 64 characters)
* Property values: strings only (max 500 characters)

<Tabs>
  <Tab title="curl">
    ```bash {15-21} theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/send \
      --request POST \
      --header 'x-dialect-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "recipient": {
          "type": "subscriber",
          "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
        },
        "channels": ["IN_APP", "PUSH"],
        "message": {
          "title": "Trade Executed Successfully",
          "body": "Your swap of 100 USDC to SOL has been completed."
        },
        "data": {
          "type": "transaction",
          "transactionId": "3x7Kj9mNp...",
          "amount": "100",
          "fromToken": "USDC",
          "toToken": "SOL"
        }
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript {11-17} theme={null}
    const alertWithData = {
      recipient: {
        type: 'subscriber',
        walletAddress: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'
      },
      channels: ['IN_APP', 'PUSH'],
      message: {
        title: 'Trade Executed Successfully',
        body: 'Your swap of 100 USDC to SOL has been completed.'
      },
      data: {
        type: 'transaction',
        transactionId: '3x7Kj9mNp...',
        amount: '100',
        fromToken: 'USDC',
        toToken: 'SOL'
      }
    };

    await fetch(`https://alerts-api.dial.to/v2/${appId}/send`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(alertWithData)
    });
    ```
  </Tab>
</Tabs>

<Note>
  The `data` object is stored with the notification and can be retrieved later from the [notification history endpoint](/api-reference/integrate-an-inbox/get-notification-history). This makes it perfect for implementing deep linking or passing context to your application.
</Note>

## Step 5: Topic-Based Messaging

If you've configured notification topics, you can send targeted messages to users who have subscribed to specific categories.

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://alerts-api.dial.to/v2/{appId}/send \
      --request POST \
      --header 'x-dialect-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "recipient": {
          "type": "all-subscribers"
        },
        "channels": ["EMAIL", "IN_APP"],
        "message": {
          "title": "🗳️ New Governance Proposal: Protocol Upgrade",
          "body": "A new governance proposal is now live for voting. Your participation matters for the future of our protocol."
        },
        "topicId": "governance-updates"
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const governanceUpdate = {
      recipient: {
        type: 'all-subscribers'
      },
      channels: ['EMAIL', 'IN_APP'],
      message: {
        title: '🗳️ New Governance Proposal: Protocol Upgrade',
        body: 'A new governance proposal is now live for voting. Your participation matters for the future of our protocol.'
      },
      topicId: 'governance-updates'
    };

    await fetch(`https://alerts-api.dial.to/v2/${appId}/send`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(governanceUpdate)
    });
    ```
  </Tab>
</Tabs>

## Message Examples by Use Case

### Welcome Message

```typescript theme={null}
const welcomeMessage = {
  recipient: {
    type: 'subscriber',
    walletAddress: userWallet
  },
  channels: ['EMAIL', 'IN_APP'],
  message: {
    title: 'Welcome to [Your App]! 🎉',
    body: 'Thanks for subscribing! You will now receive important updates and alerts.',
    actions: [
      { 
        type: 'link', 
        label: 'Get Started', 
        url: 'https://yourapp.com/onboarding' 
      }
    ]
  }
};
```

### Transaction Alert

```typescript theme={null}
const transactionAlert = {
  recipient: {
    type: 'subscriber',
    walletAddress: userWallet
  },
  channels: ['IN_APP', 'EMAIL'],
  message: {
    title: 'Transaction Confirmed ✅',
    body: 'Your 0.5 SOL transfer to 3x7Kj...9mNp has been confirmed.'
  }
};
```

### Security Alert

```typescript theme={null}
const securityAlert = {
  recipient: {
    type: 'subscriber',
    walletAddress: userWallet
  },
  channels: ['EMAIL', 'IN_APP'],
  message: {
    title: '🔒 Security Alert: New Login Detected',
    body: 'A new login to your account was detected from a new device. If this was not you, please secure your account immediately.',
    actions: [
      { 
        type: 'link', 
        label: 'Review Security', 
        url: 'https://yourapp.com/security' 
      }
    ]
  }
};
```

### Price Alert

```typescript theme={null}
const priceAlert = {
  recipient: {
    type: 'subscriber',
    walletAddress: userWallet
  },
  channels: ['IN_APP'],
  message: {
    title: '📈 Price Alert: SOL +12%',
    body: 'Solana is up 12% in the last hour, now trading at $145. Your portfolio value has increased by $340.',
    actions: [
      { 
        type: 'link', 
        label: 'View Portfolio', 
        url: 'https://yourapp.com/portfolio' 
      }
    ]
  },
  topicId: 'price-alerts'
};
```

## Error Handling

### Common Response Codes

**202 Accepted**: Message sent successfully

```json theme={null}
{}
```

**400 Bad Request**: Invalid request format

```json theme={null}
{
  "error": {
    "message": "Validation failed",
    "details": "Title is required"
  }
}
```

**401 Unauthorized**: Invalid API key

```json theme={null}
{
  "error": "Unauthorized"
}
```

**403 Forbidden**: Access denied

```json theme={null}
{
  "error": "Forbidden"
}
```

### Error Handling Example

```typescript theme={null}
async function sendNotificationSafely(appId: string, apiKey: string, message: any) {
  try {
    const response = await fetch(`https://alerts-api.dial.to/v2/${appId}/send`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(message)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`HTTP ${response.status}: ${JSON.stringify(error)}`);
    }

    console.log('✅ Message sent successfully');
    return { success: true };

  } catch (error) {
    console.error('❌ Message sending failed:', error);
    
    if (error.message.includes('401')) {
      return { 
        success: false, 
        error: 'Invalid API key',
        code: 'UNAUTHORIZED'
      };
    } else if (error.message.includes('400')) {
      return { 
        success: false, 
        error: 'Invalid request format',
        code: 'BAD_REQUEST'
      };
    } else {
      return { 
        success: false, 
        error: 'Unknown error occurred',
        code: 'UNKNOWN_ERROR'
      };
    }
  }
}
```

## Best Practices

💡 **Message Design Tips**:

* Keep titles concise and descriptive (especially important for email subjects)
* Structure longer messages with clear sections
* Always include clear calls-to-action when appropriate
* Use HTML formatting only for email channels

💡 **Technical Tips**:

* Test your messages across different channels (IN\_APP vs email vs Telegram)
* Implement proper error handling and retry logic for critical notifications
* Use batch sending for multiple recipients to improve efficiency
* Consider user time zones when sending time-sensitive notifications

💡 **User Experience Tips**:

* Respect user preferences and subscription settings
* Provide context in your messages - users should understand why they're receiving the notification
* Use topic-based messaging to ensure relevance
* Make action buttons clear and valuable


# Send Alerts via Dashboard
Source: https://docs.dialect.to/alerts/send/dashboard

Send one-off notifications and marketing announcements using Dialect's no-code dashboard interface

This guide focuses on the sending workflow - for dashboard setup and management, see the [dashboard introduction](/alerts/setup/dashboard-introduction).

**Ready to send notifications?** → [Go to Dialect Dashboard](https://dashboard.dialect.to)

## Prerequisites

Before sending alerts via dashboard, ensure you have:

* ✅ Connected your wallet to the dashboard
* ✅ [Registered your app](/alerts/setup/register-app) with Dialect
* ✅ At least one subscriber to receive your alerts

## Quick Overview

The dashboard provides a composer interface for sending notifications without writing code. Perfect for:

* Marketing announcements and product updates
* Community notifications and event reminders
* Testing notification content and delivery

## Sending Dashboard Alerts

<video alt="Walkthrough of sending a dashboard alert" />

<br />

### Complete Alert Workflow

<Steps>
  <Step title="Access Dashboard">
    Go to [dashboard.dialect.to](https://dashboard.dialect.to), connect your dApp's wallet, and click "Alerts" then "Send a new alert"
  </Step>

  <Step title="Select Topic">
    * **General Broadcast**: Default topic available for all apps
    * **Custom Topics**: Create specific categories (product updates, timely alerts, etc.)
    * Users can subscribe to specific topics for better control over notifications
  </Step>

  <Step title="Choose Recipients">
    The dashboard supports multiple recipient options:

    * **All Subscribers**: Send to all users subscribed to the selected topic, or all app subscribers if no topic was chosen
    * **Specific Recipients**: Enter comma-separated wallet addresses (single address for one person, up to 10,000 addresses per message)
  </Step>

  <Step title="Select Delivery Channel">
    Choose one or multiple delivery channels for your alert:

    * **Inbox**: In-app notifications displayed in your integrated notification widget
    * **Telegram**: Messages sent directly to users' Telegram accounts
    * **Email**: Professional email notifications

    <Note>
      You can select multiple channels to send the same message across different delivery methods simultaneously. To do so, just click on the channel icon.
    </Note>
  </Step>

  <Step title="Create Alert Content">
    * **Title**: Short, attention-grabbing headline
    * **Message**: Main notification content
    * **Call-to-Action**: Optional button with custom label and URL
    * **Image**: Optional image upload to enhance your message
  </Step>

  <Step title="Test and Send">
    * **Send Test Alert**: Optional - send to specific wallet address to preview
    * **Review and Send**: Final review before delivery
    * **Confirmation**: Dashboard shows delivery status and timestamp
  </Step>
</Steps>

### Channel-Specific Specifications

Based on your selected delivery channel, follow these specifications:

<Tabs>
  <Tab title="Email Channel">
    **Email Configuration:**

    * **Rich HTML Editor**: Full formatting support
    * **Character Limit**: 4,096 characters
    * **Images**: Use HTML `<img>` tags (no file uploads)
    * **Call-to-Action**: Add button with label and URL
    * **Subject Line**: Should be clear and actionable as it appears as the notification title
  </Tab>

  <Tab title="Inbox Channel">
    **Inbox Configuration:**

    * **Plain Text Editor**: No HTML formatting
    * **Character Limit**: 800 characters
    * **Image Upload**: Single image, 1:1 ratio, 100KB max
    * **Display Location**: Notification bell component in your React app
    * **Title**: Should be short and attention-grabbing
  </Tab>

  <Tab title="Telegram Channel">
    **Telegram Configuration:**

    * **Text Only**: No HTML or image support
    * **Character Limit**: 4,096 characters
    * **Call-to-Action**: URL only (will show as clickable link)
    * **Emojis**: Use sparingly to add visual appeal
    * **URLs**: Include full URLs for any action links
  </Tab>
</Tabs>

### Dashboard Limitations

**Current Limitations:**

* ❌ **No Scheduled Sending**: All notifications send immediately
* ❌ **No Bulk Content**: Each channel must be configured individually
* ❌ **No Templates**: Content must be written fresh each time
* ❌ **No A/B Testing**: Single message version per channel

**Workarounds:**

* **For Scheduled Sending**: Use programmatic alerts with your own scheduling
* **For Templates**: Save content in external documents for copy/paste
* **For Bulk Operations**: Use the REST API for automated sending

## Best Practices

### Content Guidelines

1. **Clear Value Proposition**: Explain why this notification matters
2. **Action-Oriented**: Include clear next steps for users
3. **Brand Consistent**: Maintain your voice and tone
4. **Mobile-Friendly**: Consider how content appears on mobile devices

### Timing Strategy

1. **Know Your Audience**: Send when users are most active
2. **Respect Time Zones**: Use scheduling for global audiences
3. **Frequency Limits**: Don't overwhelm users with too many alerts
4. **Event-Driven**: Tie notifications to relevant user actions or milestones

### Channel Selection

1. **EMAIL**: Professional announcements, detailed updates
2. **TELEGRAM**: Quick updates, community engagement
3. **INBOX**: Cross-app visibility, reaches users in integrated applications

**Ready to start sending?** → [Launch the Dashboard](https://dashboard.dialect.to)

## Integration with Other Methods

Dashboard alerts work seamlessly with other Dialect notification methods:

### Programmatic + Dashboard Hybrid

* Use our [APIs](/alerts/send/api) and [SDK](/alerts/send/sdk) for real-time, event-driven notifications
* Use dashboard alerts for planned communications and announcements
* Both methods share the same recipient base and notification topics

### Consistent User Experience

* Users receive notifications through their preferred channels regardless of sending method
* Unified notification history across all sending approaches

## Next Steps

* **Need more control?** Explore programmatic alerts for custom logic via our [SDK](/alerts/send/sdk) or [API](/alerts/send/api)
* **Want event detection?** Check out our [monitoring section](/alerts/alerts-and-monitoring) for triggered alerts


# Sending Alerts
Source: https://docs.dialect.to/alerts/send/index

Learn how to send notifications to your users through Dialect Alerts. There are three main approaches to sending alerts, each suited for different use cases and technical requirements.

## Overview of Sending Methods

### 1. Programmatic Alerts

Send alerts directly from your backend code using our APIs or SDKs. This is the most flexible approach and allows for complex logic, real-time event handling, and integration with your existing systems.

**Best for:** Real-time notifications, complex business logic, high-volume sending, custom integrations.

**Options:**

* **[REST API](/alerts/send/api/index)**: Direct HTTP calls for any programming language
* **[TypeScript SDK](/alerts/send/sdk/index)**: Simplified integration with type safety and helper functions

### 2. Dashboard Alerts

Send alerts through our no-code [dashboard](/alerts/send/dashboard) interface. Perfect for marketing announcements, product updates, and any other type of communications that don't require backend integration.

**Best for:** Marketing teams, product announcements, scheduled campaigns (soon), non-technical users.

### 3. Monitoring and Event Detection

Automatically trigger alerts based on on-chain or off-chain events. Our monitoring system can detect complex patterns and automatically send notifications when conditions are met.

**Best for:** DeFi protocols, NFT marketplaces, trading applications, automated risk management.

**Options:**

* **[Dialect Monitor](/alerts/alerts-and-monitoring/setup-event-detection)**: Our open-source monitoring tooling for new integrations or those who want to switch
* **[Custom Event Detection](/alerts/alerts-and-monitoring/integrate-existing-system)**: Integrate with your existing event systems

## Key Messaging Concepts

Before sending alerts, understand these core concepts:

* **Topics**: Categories that organize your notifications (e.g., "Price Alerts", "Liquidation Warnings")
* **Subscribers**: Users who have opted in to receive notifications from your app
* **Channels**: How notifications are delivered - EMAIL, TELEGRAM, IN\_APP, and PUSH
* **Push Notifications**: Only available to app owners; other projects send via IN\_APP channel, which receiving apps can display as push notifications

📚 **[Learn more about topics, channels, and subscribers →](/alerts/setup/topics-channels-subscribers)**

## Getting Started

1. **For immediate testing**: Start with [Dashboard Alerts](/alerts/send/dashboard) - no coding required
2. **For production integration**: Begin with programmatic alerts using our [API](/alerts/send/api/index) or [SDK](/alerts/send/sdk/index)
3. **For automated notifications**: Explore [Monitoring and Event Detection](/alerts/alerts-and-monitoring/index) for hands-off operation


# Introduction
Source: https://docs.dialect.to/alerts/send/sdk/index

Send notifications programmatically from your Node.js and React applications with full type safety and developer experience using the TypeScript SDK

## Overview

The Dialect TypeScript SDK enables you to:

* **Register your Project** to start sending messages
* **Send notifications** to individual users or broadcast to all subscribers
* **Manage user subscriptions** programmatically from your backend
* **Handle channel preferences** for email, Telegram, and in-app notifications
* **Configure notification topics** to organize different types of alerts

## Why Use the TypeScript SDK?

While our [REST API](/alerts/send/api/) works with any programming language, the TypeScript SDK offers significant advantages, such as:

* ✅ **Type Safety**: Full TypeScript definitions prevent runtime errors
* ✅ **Developer Experience**: IntelliSense, autocomplete, and inline documentation
* ✅ **Error Handling**: Comprehensive error types and retry logic
* ✅ **Authentication**: Built-in credential management and token handling
* ✅ **Performance**: Automatic request batching and connection pooling

## Use Cases

### Backend Services

* **Event-driven notifications**: Send alerts when specific events occur in your application (also have a look into our [Monitoring SDK](/alerts/alerts-and-monitoring/index) for advanced use-cases)
* **User onboarding**: Welcome messages and guided workflows
* **System alerts**: Security notifications, maintenance updates, status changes
* **Transactional notifications**: Order confirmations, payment receipts, shipping updates

### Frontend Applications

* **Subscription management**: Let users control their notification preferences
* **Real-time updates**: Show in-app notifications and manage notification history
* **Channel configuration**: Allow users to add email, Telegram, and other contact methods


# Send Messages
Source: https://docs.dialect.to/alerts/send/sdk/send-messages

Send notifications to your users through various channels using the TypeScript SDK with comprehensive examples for targeted delivery, actionable notifications, and broadcast messaging

## Prerequisites

Before sending messages, ensure you have completed these steps:

1. **App Registration**: Register your app with Dialect (see the [registration guide](/alerts/setup/register-app) if you need to set this up)
2. **SDK Setup**: Initialize the Dialect SDK (see our [Setup & Configuration guide](/alerts/send/sdk/setup-configuration) if you haven't done this yet)
3. **User Subscriptions**: Have users subscribed to your app (see our [User Management guide](/alerts/integrate-inbox/user-management) for subscription setup)

## Message Delivery Overview

Dialect's messaging system provides flexible delivery options:

1. **Channel Selection**: Messages are sent according to user channel preferences (IN\_APP, email, Telegram)
2. **User Targeting**: Send to individual users, groups, or broadcast to all subscribers
3. **Rich Content**: Support for titles, actions, images, and formatted content
4. **Topic-Based**: Optional targeting based on notification types/topics

## Step 1: Basic Message Sending

### Send to a Single User

Send a notification to a specific user's wallet address. This is the most common messaging pattern.

```typescript theme={null}
// Basic message to a single user
const recipient = "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM";

const message = {
  title: "Welcome to Our Platform! 🎉",
  message: "Thanks for joining us. Get started by exploring our features.",
  recipient,
};

await dapp.messages.send(message);
```

### Send to Multiple Users

Send the same notification to a specific set of users by providing multiple wallet addresses.

```typescript theme={null}
// Message to multiple specific users
const recipients = [
  "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "AnotherWalletAddress123...",
  "YetAnotherWallet456..."
];

const message = {
  title: "System Maintenance Notice",
  message: "We'll be performing scheduled maintenance tonight from 2-4 AM UTC.",
  recipients,
};

await dapp.messages.send(message);
```

### Broadcast to All Users

Send notifications to all users subscribed to your app. When no recipient is specified, Dialect defaults to broadcasting to all subscribers.

```typescript theme={null}
// Broadcast to all subscribed users
const message = {
  title: "Major Update Released! 🚀",
  message: "Version 2.0 is now live with exciting new features.",
};

await dapp.messages.send(message);
```

## Step 2: Channel-Specific Delivery

### Target Email and Telegram

Control which channels receive your message by specifying `addressTypes`. Note that IN\_APP notifications are always delivered, so you only need to specify additional channels like Email and Telegram.

```typescript theme={null}
import { AddressType } from '@dialectlabs/sdk';

// Send via email and Telegram (IN_APP is automatic)
const weeklyUpdate = {
  title: "Weekly Portfolio Summary",
  message: "Here's your portfolio performance for this week...",
  recipient: userWallet,
  addressTypes: [AddressType.Email, AddressType.Telegram]
};

await dapp.messages.send(weeklyUpdate);
```

### Email-Optimized Messages

When sending to email channels, ensure you provide a clear title as it becomes the email subject line.

```typescript theme={null}
import { AddressType } from '@dialectlabs/sdk';

// Email-optimized notification
const emailNotification = {
  title: "Transaction Confirmation - Order #12345", // Email subject
  message: `
    Your transaction has been processed successfully.
    
    Order Details:
    - Amount: 0.5 SOL
    - Fee: 0.0025 SOL
    - Transaction ID: 3x7Kj...9mNp
    
    View full details in your dashboard.
  `,
  recipient: userWallet,
  addressTypes: [AddressType.Email]
};

await dapp.messages.send(emailNotification);
```

## Step 3: Interactive & Rich Messages

### Actionable Notifications

Add buttons to your notifications that allow users to take immediate action. Currently supports one action button that can direct users to a website.

```typescript theme={null}
import { DappMessageActionType } from '@dialectlabs/sdk';

// Notification with action button
const recipient = "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM";

// Action button configuration
const actionsV2 = {
  type: DappMessageActionType.LINK,
  links: [{ 
    label: "Claim Rewards", 
    url: "https://yourapp.com/claim-rewards" 
  }],
};

const rewardNotification = {
  title: "Staking Rewards Ready! 🎯",
  message: "You've earned 0.15 SOL in staking rewards. Click below to claim them.",
  recipient,
  actionsV2,
};

await dapp.messages.send(rewardNotification);
```

### Rich Content Messages

Include additional context and formatting to make your messages more engaging and informative. Email channels support full HTML formatting, while other channels use plain text.

```typescript theme={null}
import { DappMessageActionType, AddressType } from '@dialectlabs/sdk';

const actionsV2 = {
  type: DappMessageActionType.LINK,
  links: [{ 
    label: "View Portfolio", 
    url: "https://yourapp.com/portfolio" 
  }],
};

// Rich HTML content for email channel
const emailMessage = {
  title: "Price Alert: SOL Hit Your Target! 📈",
  message: `
    <h2>🎉 Great news! Solana has reached your target price.</h2>
    
    <table style="width: 100%; border-collapse: collapse; margin: 20px 0;">
      <tr>
        <td style="padding: 10px; border: 1px solid #ddd;"><strong>📊 Current Price:</strong></td>
        <td style="padding: 10px; border: 1px solid #ddd;">$145.50</td>
      </tr>
      <tr>
        <td style="padding: 10px; border: 1px solid #ddd;"><strong>🎯 Your Target:</strong></td>
        <td style="padding: 10px; border: 1px solid #ddd;">$140.00</td>
      </tr>
      <tr>
        <td style="padding: 10px; border: 1px solid #ddd;"><strong>📈 Gain:</strong></td>
        <td style="padding: 10px; border: 1px solid #ddd; color: green;">+3.9%</td>
      </tr>
    </table>
    
    <p><em>Consider reviewing your position and taking action.</em></p>
  `,
  recipient: userWallet,
  addressTypes: [AddressType.Email], // HTML only works for email
  actionsV2
};

// Plain text version for IN_APP and Telegram
const plainTextMessage = {
  title: "Price Alert: SOL Hit Your Target! 📈",
  message: `
    Great news! Solana has reached your target price.
    
    📊 Current Price: $145.50
    🎯 Your Target: $140.00
    📈 Gain: +3.9%
    
    Consider reviewing your position and taking action.
  `,
  recipient: userWallet,
  addressTypes: [AddressType.Telegram], // Plain text for non-email channels
  actionsV2
};

// Send both versions
await dapp.messages.send(emailMessage);
await dapp.messages.send(plainTextMessage);
```

## Step 4: Topic-Based Messaging

### Send to Topic Subscribers

If you've configured notification types/topics, you can send targeted messages to users who have subscribed to specific categories.

```typescript theme={null}
// Send to users subscribed to a specific notification type
const defiAlert = {
  title: "New DeFi Opportunity Available",
  message: "A new high-yield farming pool has been added with 15% APY.",
  notificationTypeId: "defi-alerts", // Your configured topic ID
};

await dapp.messages.send(defiAlert);
```

### Topic-Specific Content

Tailor your message content to match the expectations of users who subscribed to specific topics.

```typescript theme={null}
import { DappMessageActionType } from '@dialectlabs/sdk';

const actionsV2 = {
  type: DappMessageActionType.LINK,
  links: [{ 
    label: "Vote Now", 
    url: "https://yourapp.com/governance/proposals/123" 
  }],
};

// Governance topic notification
const governanceUpdate = {
  title: "🗳️ New Governance Proposal: Protocol Upgrade",
  message: `
    A new governance proposal is now live for voting:
    
    📋 Proposal: Upgrade to V3 Protocol
    ⏰ Voting Period: 7 days remaining
    📊 Current Status: 45% participation
    
    Your vote matters for the future of our protocol.
  `,
  notificationTypeId: "governance-updates",
  actionsV2,
};

await dapp.messages.send(governanceUpdate);
```

## Message Examples by Use Case

### Welcome Message

```typescript theme={null}
import { DappMessageActionType } from '@dialectlabs/sdk';

const actionsV2 = {
  type: DappMessageActionType.LINK,
  links: [{ label: "Get Started", url: "https://yourapp.com/onboarding" }],
};

const welcomeMessage = {
  title: "Welcome to [Your App]! 🎉",
  message: "Thanks for subscribing! You'll now receive important updates and alerts.",
  recipient: userWallet,
  actionsV2
};

await dapp.messages.send(welcomeMessage);
```

### Transaction Alert

```typescript theme={null}
import { AddressType } from '@dialectlabs/sdk';

const transactionAlert = {
  title: "Transaction Confirmed ✅",
  message: "Your 0.5 SOL transfer to 3x7Kj...9mNp has been confirmed.",
  recipient: userWallet,
  addressTypes: [AddressType.Email] // Also send email record
};

await dapp.messages.send(transactionAlert);
```

### Security Alert

```typescript theme={null}
import { DappMessageActionType, AddressType } from '@dialectlabs/sdk';

const actionsV2 = {
  type: DappMessageActionType.LINK,
  links: [{ label: "Review Security", url: "https://yourapp.com/security" }],
};

const securityAlert = {
  title: "🔒 Security Alert: New Login Detected",
  message: "A new login to your account was detected from a new device. If this wasn't you, please secure your account immediately.",
  recipient: userWallet,
  addressTypes: [AddressType.Email], // Ensure they get email notification
  actionsV2
};

await dapp.messages.send(securityAlert);
```

### Price Alert

```typescript theme={null}
import { DappMessageActionType } from '@dialectlabs/sdk';

const actionsV2 = {
  type: DappMessageActionType.LINK,
  links: [{ label: "View Portfolio", url: "https://yourapp.com/portfolio" }],
};

const priceAlert = {
  title: "📈 Price Alert: SOL +12%",
  message: "Solana is up 12% in the last hour, now trading at $145. Your portfolio value has increased by $340.",
  notificationTypeId: "price-alerts",
  recipient: userWallet,
  actionsV2
};

await dapp.messages.send(priceAlert);
```

## Best Practices

💡 **Message Design Tips**:

* Keep titles concise and descriptive (especially important for email subjects)
* Structure longer messages with clear sections
* Always include clear calls-to-action when appropriate

💡 **Technical Tips**:

* Test your messages across different channels (IN\_APP vs email vs Telegram)
* Implement proper error handling and retry logic for critical notifications
* Consider user time zones when sending time-sensitive notifications

💡 **User Experience Tips**:

* Respect user preferences and subscription settings
* Provide context in your messages - users should understand why they're receiving the notification
* Use topic-based messaging to ensure relevance


# Setup & Configuration
Source: https://docs.dialect.to/alerts/send/sdk/setup-configuration

Install and configure the Dialect TypeScript SDK for sending notifications from your Node.js and React applications

Get the Dialect TypeScript SDK installed and configured in your environment. This guide covers installation, client setup, authentication, and environment configuration.

## Installation

Install the core SDK and blockchain-specific packages for your needs:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    # Core SDK (required)
    npm install @dialectlabs/sdk

    # Blockchain SDK for Solana
    npm install @dialectlabs/blockchain-sdk-solana
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    # Core SDK (required)
    yarn add @dialectlabs/sdk

    # Blockchain SDK for Solana
    yarn add @dialectlabs/blockchain-sdk-solana
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    # Core SDK (required)
    pnpm add @dialectlabs/sdk

    # Blockchain SDK for Solana
    pnpm add @dialectlabs/blockchain-sdk-solana
    ```
  </Tab>
</Tabs>

## App Registration

Before using the SDK, you need to register your app. You can do this either:

1. **Via Dashboard**: Follow our [Dashboard registration guide](/alerts/setup/register-app) to register
2. **Via SDK**: Register programmatically using the [SDK tab in the registration guide](/alerts/setup/register-app#sdk)

## Wallet Credentials Setup

**If you registered via SDK**: Your `DIALECT_SDK_CREDENTIALS` should already be set up from the registration process.

**If you registered via Dashboard**: You need to extract the private key from the wallet you used to register and format it as `DIALECT_SDK_CREDENTIALS`. Your app is tied to the specific keypair used during registration:

1. **Export from your wallet app**: Open Phantom, Solflare, etc. → Settings → Export Private Key → Copy the private key
2. **Convert to array format**: Use a tool like [this](https://www.npmjs.com/package/@solana/web3.js) to convert base58 private key to JSON array format `[170,23,...,300]`
3. **Set in environment**: Add the array format to your `.env` file as `DIALECT_SDK_CREDENTIALS`

<Warning>
  **You must use the same wallet that was used to register your app.** The app registration is tied to that specific keypair and cannot be changed to a different wallet.
</Warning>

<Warning>
  **Secure Your Credentials**: Keep your `DIALECT_SDK_CREDENTIALS` secure. This is your app's private key and should never be exposed in client-side code or committed to version control.
</Warning>

## SDK Client Setup

### Basic SDK Initialization

```typescript theme={null}
import { Dialect, DialectCloudEnvironment, DialectSdk } from "@dialectlabs/sdk";
import {
  Solana,
  SolanaSdkFactory,
  NodeDialectSolanaWalletAdapter,
} from "@dialectlabs/blockchain-sdk-solana";

// Initialize SDK
const environment: DialectCloudEnvironment = "development";
const dialectSolanaSdk: DialectSdk<Solana> = Dialect.sdk(
  {
    environment,
  },
  SolanaSdkFactory.create({
    // IMPORTANT: must set environment variable DIALECT_SDK_CREDENTIALS
    // to your dapp's Solana messaging wallet keypair e.g. [170,23, . . . ,300]
    wallet: NodeDialectSolanaWalletAdapter.create(),
  })
);

// Load your dApp
const dapp = await dialectSolanaSdk.dapps.find();

if (!dapp) {
  throw new Error("Dapp not found. Please register your app first.");
}

console.log('✅ SDK initialized and dApp loaded!');
```

### Environment-Specific Setup

```typescript theme={null}
// For production deployment, update the environment
const environment: DialectCloudEnvironment = "production"; // Change to "development" for testing

const dialectSolanaSdk = Dialect.sdk(
  {
    environment,
  },
  SolanaSdkFactory.create({
    // IMPORTANT: must set environment variable DIALECT_SDK_CREDENTIALS
    // to your dapp's Solana messaging wallet keypair e.g. [170,23, . . . ,300]
    wallet: NodeDialectSolanaWalletAdapter.create(),
  })
);
```

## Troubleshooting

### Common Issues

**1. Invalid Credentials**

```bash theme={null}
Error: Invalid wallet credentials
# Solution: Check your DIALECT_SDK_CREDENTIALS format
echo $DIALECT_SDK_CREDENTIALS | jq . # Should be valid JSON array
```

**2. Dapp Not Found**

```bash theme={null}
Error: Dapp not found
# Solution: Register your app first via dashboard or SDK
```


# Dashboard Introduction
Source: https://docs.dialect.to/alerts/setup/dashboard-introduction

Setup your app, send notifications, and manage your project with no code required. Perfect for one-off messages, testing notifications, or managing your settings and API keys — all through an intuitive interface.

<Card title="Visit the Dialect Dashboard" icon="gauge" href="https://dashboard.dialect.to">
  Access your project dashboard to register, send alerts, and configure settings.
</Card>

## Dashboard Tour

<iframe title="YouTube video player" />

Watch this complete walkthrough of the Version 2 dashboard, covering project registration, sending alerts, managing settings, and testing the full notification flow.

## Dashboard Features

Explore what you can do with each dashboard section:

<CardGroup>
  <Card title="Alerts" icon="bell" href="https://dashboard.dialect.to/alerts">
    Send no-code notifications across multiple channels - inbox, email, and Telegram.
  </Card>

  <Card title="Events" icon="calendar-days" href="https://dashboard.dialect.to/events">
    Receive real-time updates on price change events and trending tokens.
  </Card>

  <Card title="Markets" icon="chart-line" href="https://dashboard.dialect.to/markets">
    Get up to date market data, such as lending rates and positions for your wallet.
  </Card>

  <Card title="Blinks" icon="link" href="https://dashboard.dialect.to/blinks">
    Create interactive blockchain experiences from simple URLs.
  </Card>

  <Card title="API Keys" icon="key" href="https://dashboard.dialect.to/api-keys">
    Manage your project's API keys.
  </Card>

  <Card title="Settings" icon="gear" href="https://dashboard.dialect.to/settings">
    Configure your project details, logo, and account preferences.
  </Card>
</CardGroup>

## Getting Started

### 1. Register Your Project

**[Complete app registration →](/alerts/setup/register-app)**

Connect your wallet, upload your logo, and add project details to access the dashboard.

### 2. Subscribe for Notifications

**[Visit the scaffold →](https://alerts-example.dialect.to)**

Test the subscription flow and see how users will interact with your notifications.

### 3. Send Your First Alert

**[Send via dashboard →](/alerts/send/dashboard)**

Choose recipients, select channels, create your message, and send notifications with no code required.

> 💡 **Pro Tip**: Use the feedback button in the dashboard to request specific features and help us prioritize development.

## Next Steps

### Create Topics & Manage Subscribers

**[Topics & Subscribers →](/alerts/setup/topics-channels-subscribers)**

Set up custom notification categories and manage your subscriber base.

### Send Programmatic Alerts

**[API →](/alerts/send/api) • [SDK →](/alerts/send/sdk/send-messages)**

Integrate notification sending directly into your application code.

### Add UI Components

**[Integrate an inbox →](/alerts/integrate-inbox)**

Add Dialect's notification UI components to your app.


# App Registration
Source: https://docs.dialect.to/alerts/setup/register-app

Register your application with Dialect and start sending or receiving notifications.

<video alt="Walkthrough of registering your app on the Dialect dashboard" />

## Registration Methods

<Tabs>
  <Tab title="Dashboard (Recommended)">
    1. Access the [Dialect Developer Dashboard](https://dashboard.dialect.to)
    2. Connect your wallet (We highly recommend using a new keypair)
    3. Click on Alerts
    4. Register your Project

    **Required Fields:**

    * **Project Name**: Public name users will see
    * **Description**: Brief explanation of your app's purpose
    * **Project Logo**: App icon (recommended: 256x256px PNG max. 1MB)
  </Tab>

  <Tab title="SDK">
    **Step 1: Install packages**

    ```bash theme={null}
    npm install @dialectlabs/sdk @dialectlabs/blockchain-sdk-solana
    ```

    **Step 2: Create a keypair for your app**

    <Warning>
      Creating a keypair is analogous to creating a username & password. It's important to securely create and manage your keypair, as it will be used to access your Dialect account.
    </Warning>

    ```bash theme={null}
    # Create new keypair
    solana-keygen new -o <your-app-name>-messaging-keypair.json

    # Get the public key
    solana-keygen publickey <your-app-name>-messaging-keypair.json > app-pubkey.pub
    ```

    **Step 3: Set environment variable**

    ```bash theme={null}
    # Set your keypair as environment variable (use the array format from your keypair file)
    export DIALECT_SDK_CREDENTIALS="[170,23,...,300]"
    ```

    **Step 4: Register programmatically**

    ```typescript theme={null}
    import { Dialect, DialectCloudEnvironment, DialectSdk, BlockchainType } from "@dialectlabs/sdk";
    import {
      Solana,
      SolanaSdkFactory,
      NodeDialectSolanaWalletAdapter,
    } from "@dialectlabs/blockchain-sdk-solana";

    const environment: DialectCloudEnvironment = "production"; // or "development"

    // Create SDK instance
    const sdk: DialectSdk<Solana> = Dialect.sdk(
      {
        environment,
      },
      SolanaSdkFactory.create({
        // IMPORTANT: must set environment variable DIALECT_SDK_CREDENTIALS
        // to your dapp's Solana keypair e.g. [170,23, . . . ,300]
        wallet: NodeDialectSolanaWalletAdapter.create(),
      })
    );

    // Register your app
    const dapp = await sdk.dapps.create({
      name: "My App Name",
      description: "Brief description of what my app does",
      blockchainType: BlockchainType.SOLANA,
    });

    console.log('App registered successfully:', dapp);
    ```

    <Warning>
      **Always create a new wallet for each app.** Never reuse existing wallet keypairs from other applications or personal wallets. This ensures proper security isolation and prevents unauthorized access to your notification system.
    </Warning>

    <Warning>
      Keep your `DIALECT_SDK_CREDENTIALS` secure. This is your app's private key and should never be exposed in client-side code or committed to version control.
    </Warning>

    <Tip>
      Dialect's database *never* stores your app's private keys, only the public key.
    </Tip>
  </Tab>

  <Tab title="API">
    Coming soon! For now, please use the Dashboard or SDK methods above.
  </Tab>
</Tabs>

Your app is now ready to send notifications! 🎉

## Next Steps

After successful registration:

1. **[Understand core concepts](/alerts/setup/topics-channels-subscribers)** - Learn about topics, channels, and subscribers
2. **[Explore the dashboard](/alerts/setup/dashboard-introduction)** - Manage your app and monitor usage
3. **[Send your first notification](/alerts/send/index)** - Start integrating notification sending
4. **[Universal Inbox Guide](/alerts/integrate-inbox/index)** - Integrate an Inbox using APIs or advanced UI components


# Topics & Channels Logic
Source: https://docs.dialect.to/alerts/setup/topics-channels-subscribers

Understanding the core concepts of Dialect's notification system: how topics organize notifications, channels deliver them, and subscribers receive them.

<img alt="Dialect notification inbox showing configurable topics, channels, and subscribers" />

<img alt="Dialect notification inbox showing configurable topics, channels, and subscribers" />

## Overview

Dialect's notification system is built around three fundamental concepts that work together to create flexible, scalable notification experiences.

<img alt="Diagram showing how topics, channels, and subscribers work together in Dialect's notification system" />

<img alt="Diagram showing how topics, channels, and subscribers work together in Dialect's notification system" />

### The Flow

1. **Users subscribe** to topics they care about and choose how they want to be notified
2. **Your app sends** notifications to relevant topics when events happen
3. **Dialect delivers** those notifications to subscribers via their chosen channels

## Topics

**Topics** define *what* notifications are about. They categorize and organize different types of alerts your application sends.

### What are Topics?

Think of topics as notification categories or event types:

* **Price Alerts** - Token price changes
* **Liquidation Warnings** - DeFi position risks
* **Governance Updates** - DAO proposal notifications
* **NFT Activity** - New offers and auction alerts

### Topic Best Practices

#### 1. Granular but not overwhelming

Choose topics that are specific enough to be actionable but not so granular that they become overwhelming.

Good examples:

* Liquidation warnings for critical DeFi alerts
* Price target notifications when thresholds are met
* Governance proposals for DAO updates
* Yield changes for APY updates

Avoid:

* "Everything" - Too broad and not actionable
* "BTC price up 1%" - Too specific and noisy

#### 2. Clear naming

Use clear, descriptive names that users can easily understand.

Good examples:

* "Order Shipped"
* "Payment Received"
* "Security Alert"

Avoid technical jargon like:

* "tx-confirmed-evt"
* "usr-auth-req"

#### 3. User-focused descriptions

Write descriptions that focus on user benefits rather than technical details.

Good example:
"Get alerted before your DeFi positions are at risk of liquidation"

Instead of:
"Automated liquidation risk calculation notifications"

<Card title="Learn More: Topic Management" icon="user-gear" href="/alerts/integrate-inbox/user-management">
  Explore detailed topic management workflows and user subscription patterns
</Card>

## Channels

**Channels** define *how* notifications are delivered to users. Each channel represents a different communication method.

### Available Channels

| Channel      | Description                  | Content Support                 | Best For                                 |
| ------------ | ---------------------------- | ------------------------------- | ---------------------------------------- |
| **EMAIL**    | Email notifications          | HTML formatting, rich content   | Detailed updates, newsletters, reports   |
| **TELEGRAM** | Telegram bot messages        | Text only, no images            | Real-time alerts, simple notifications   |
| **IN\_APP**  | In-application notifications | Text + single image (1:1 ratio) | User engagement, visual notifications    |
| **PUSH**     | Mobile push notifications    | Text only                       | Critical mobile alerts (app owners only) |

### Channel Characteristics

**EMAIL**

* **Content**: Full HTML support with rich formatting
* **Character Limit**: 4,096 characters
* **Images**: Via HTML `<img>` tags (not file uploads)
* **Delivery**: Reliable but not immediate (few minutes)
* **Best for**: Detailed notifications, newsletters, formatted content

**TELEGRAM**

* **Content**: Text only, no image support
* **Character Limit**: 4,096 characters
* **Links**: Supported with inline buttons
* **Delivery**: Near real-time
* **Best for**: Quick alerts, simple notifications, community updates

**IN\_APP**

* **Content**: Plain text + optional single image
* **Character Limit**: 800 characters
* **Images**: 1:1 aspect ratio, 100KB maximum
* **Display**: Shows in notification bell component
* **Delivery**: Real-time when user is active
* **Best for**: Visual notifications, feature announcements, user engagement

**PUSH** (App Owners Only)

* **Content**: Text only
* **Character Limit**: Varies by platform (iOS \~200, Android \~250)
* **Delivery**: Mobile notifications
* **Restriction**: Only available to app owners for their own users
* **Best for**: Critical alerts, time-sensitive information

<Card title="Learn More: Channel Configuration" icon="gear" href="/alerts/integrate-inbox/user-management#step-2%3A-channel-management">
  Configure channels and manage notification delivery
</Card>

## Subscribers

**Subscribers** represent *who* receives notifications. Each subscriber is a user who has opted in to receive alerts from your application.

### Subscription Methods

There are three ways to subscribe users to notifications:

1. **React Widget**: Users can subscribe by clicking the notification bell and signing a message to verify their wallet ownership. This is the simplest way to get started and works well for most dapps. For more information checkout our [Quick Start guide](/alerts/quick-start#step-4-user-subscribes-to-notifications-2-minutes).

2. **API Integration**: For wallet applications that can sign messages on behalf of users, we recommend using our API to programmatically subscribe users. This provides more control over the subscription flow and a smoother user experience. Learn more about [API Authentication](/alerts/integrate-inbox/api/authentication).

3. **SDK Integration**: Use our TypeScript/JavaScript SDK to programmatically manage subscriptions from your backend or frontend applications. This approach offers the most flexibility and is ideal for custom subscription flows and backend integrations. Learn more in our [SDK Setup Configuration](/alerts/integrate-inbox/sdk/setup-configuration).

<Card title="Learn More: Subscriber Management" icon="users" href="/alerts/integrate-inbox/user-management">
  Master subscriber workflows, API integration, and SDK setup for complete user management
</Card>

## Next Steps

Now that you understand the core concepts:

1. **[Dashboard Introduction](/alerts/setup/dashboard-introduction)** - Learn to manage topics and subscribers through the web interface
2. **[User Management](/alerts/integrate-inbox/user-management)** - Deep dive into subscriber workflows and topic management
3. **[Send Your First Alert](/alerts/send)** - Start sending notifications to subscribers
4. **[Universal Inbox Integration](/alerts/integrate-inbox/universal-inbox)** - Add notification receiving capabilities to your app
5. **[Quick Start Guide](/alerts/quick-start)** - Complete setup walkthrough with examples


# Get Blink Data Table
Source: https://docs.dialect.to/api-reference/blink-data-table/get-blink-data-table

/openapi/blinks.json get /v1/blink-data-table
Retrieve structured data in table format. Great for displaying key data, such as APY, available balance, etc.



# Get Blink List
Source: https://docs.dialect.to/api-reference/blink-lists/get-blink-list

/openapi/blinks.json get /v1/blink-lists/{id}
Retrieve curated list of Blinks by ID from the terminal



# Get Blink Preview
Source: https://docs.dialect.to/api-reference/blink-preview/get-blink-preview

/openapi/blinks.json get /v1/blink-preview
Retrieve a small, marketing-optimized preview with different images, titles, and CTA



# Execute Blink Action
Source: https://docs.dialect.to/api-reference/blink/execute-blink-action

/openapi/blinks.json post /v1/blink
Returns a ready-to-sign transaction



# Execute Chained Action
Source: https://docs.dialect.to/api-reference/blink/execute-chained-action

/openapi/blinks.json post /v1/blink/chain
Endpoint for action chaining (multi-step workflows)



# Get Full Blink
Source: https://docs.dialect.to/api-reference/blink/get-full-blink

/openapi/blinks.json get /v1/blink
Retrieve complete interactive Blink with all available actions and metadata



# Mint
Source: https://docs.dialect.to/api-reference/deficarrot/earn/mint-get

/openapi/deficarrot.json get /v0/crt/mint/{poolToken}
Get a blink for mint operations



# Mint
Source: https://docs.dialect.to/api-reference/deficarrot/earn/mint-post

/openapi/deficarrot.json post /v0/crt/mint/{poolToken}
Execute a mint operation



# Redeem
Source: https://docs.dialect.to/api-reference/deficarrot/earn/redeem-get

/openapi/deficarrot.json get /v0/crt/redeem/{poolToken}
Get a blink for redeem operations. Please note that the amount you redeem will be the amount of the stable coin you input, not the amount of the CRT token you will receive. Also there might be a small difference in the amount you receive due to the price of the stable coin and the CRT token and a withdrawal fee. Please check protocol documentation for more details.



# Redeem
Source: https://docs.dialect.to/api-reference/deficarrot/earn/redeem-post

/openapi/deficarrot.json post /v0/crt/redeem/{poolToken}
Execute a redeem operation



# Lend Deposit
Source: https://docs.dialect.to/api-reference/defituna/lend/deposit-get

/openapi/defituna.json get /v0/lend/{poolToken}/deposit
Get metadata for depositing a token into DeFiTuna.



# Lend Deposit
Source: https://docs.dialect.to/api-reference/defituna/lend/deposit-post

/openapi/defituna.json post /v0/lend/{poolToken}/deposit
Generate a transaction for depositing a token into DeFiTuna.



# Lend Withdraw
Source: https://docs.dialect.to/api-reference/defituna/lend/withdraw-get

/openapi/defituna.json get /v0/lend/{poolToken}/withdraw
Get metadata for withdrawing a token from DeFiTuna.



# Lend Withdraw
Source: https://docs.dialect.to/api-reference/defituna/lend/withdraw-post

/openapi/defituna.json post /v0/lend/{poolToken}/withdraw
Generate a transaction for withdrawing a token from DeFiTuna.



# Strategy Vault Deposit
Source: https://docs.dialect.to/api-reference/drift/vaults/deposit-get

/openapi/drift.json get /v0/vaults/strategy-vaults/{vaultId}/deposit
Get a blink for depositing to a strategy vault



# Strategy Vault Deposit
Source: https://docs.dialect.to/api-reference/drift/vaults/deposit-post

/openapi/drift.json post /v0/vaults/strategy-vaults/{vaultId}/deposit
Deposit to a strategy vault



# Request Withdraw
Source: https://docs.dialect.to/api-reference/drift/vaults/request-withdraw-get

/openapi/drift.json get /v0/vaults/strategy-vaults/{vaultId}/request-withdraw
Get a blink for requesting withdrawal from a strategy vault



# Request Withdraw
Source: https://docs.dialect.to/api-reference/drift/vaults/request-withdraw-post

/openapi/drift.json post /v0/vaults/strategy-vaults/{vaultId}/request-withdraw
Request withdrawal from a strategy vault



# Withdraw
Source: https://docs.dialect.to/api-reference/drift/vaults/withdraw-get

/openapi/drift.json get /v0/vaults/strategy-vaults/{vaultId}/withdraw
Get a blink for withdrawing from a strategy vault



# Withdraw
Source: https://docs.dialect.to/api-reference/drift/vaults/withdraw-post

/openapi/drift.json post /v0/vaults/strategy-vaults/{vaultId}/withdraw
Withdraw from a strategy vault



# Clear Notification History
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/clear-notification-history

/openapi/alerts.json post /v2/history/clear
Clear all read alerts for the given user and specified apps. This is a global action that applies across all clients



# Get Alert Topics
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/get-alert-topics

/openapi/alerts.json get /v2/topics
Retrieve available alert topics organized by application with subscription status for granular notification control



# Get Authenticated User
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/get-authenticated-user

/openapi/alerts.json get /v2/auth
Get authenticated subscriber's wallet address for identity verification and session validation



# Get Available Apps
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/get-available-apps

/openapi/alerts.json get /v2/apps
Get all applications available to the authenticated user with subscription status, topics, and channel availability



# Get Notification History
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/get-notification-history

/openapi/alerts.json get /v2/history
Retrieve user's alert history with pagination, filtering by app, and detailed notification metadata



# Get Notification Summary
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/get-notification-summary

/openapi/alerts.json get /v2/history/summary
Get quick summary of user's notification status including unread count and last read timestamp for efficient inbox management



# Mark Notifications as Read
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/mark-notifications-as-read

/openapi/alerts.json post /v2/history/read
Mark alerts as read for the authenticated user to update their notification status



# Prepare Solana Authentication
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/prepare-solana-authentication

/openapi/alerts.json post /v2/auth/solana/prepare
Generate challenge message for Solana wallet-based authentication with nonce and timestamp



# Prepare Solana Transaction Authentication
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/prepare-solana-transaction-authentication

/openapi/alerts.json post /v2/auth/solana-tx/prepare
Generate transaction for Solana wallet-based authentication using transaction signing



# Subscribe to Alert Topic
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/subscribe-to-alert-topic

/openapi/alerts.json post /v2/topics/subscribe
Enable receiving alerts for a specific topic to provide granular notification control and better user experience



# Subscribe to Alerts
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/subscribe-to-alerts

/openapi/alerts.json post /v2/subscribe
Subscribe to alerts from applications across multiple channels with support for app-specific and bulk subscriptions



# Subscribe to Push Notifications
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/subscribe-to-push-notifications

/openapi/alerts.json post /v2/push/subscribe
Register device for push notifications using Firebase Cloud Messaging (FCM) with support for app-specific or global subscriptions



# Unsubscribe from Alert Topic
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/unsubscribe-from-alert-topic

/openapi/alerts.json post /v2/topics/unsubscribe
Disable receiving alerts for a specific topic to provide granular notification control



# Unsubscribe from Alerts
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/unsubscribe-from-alerts

/openapi/alerts.json post /v2/unsubscribe
Remove subscription to alerts from specified applications and channels with bulk unsubscription support



# Unsubscribe from Push Notifications
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/unsubscribe-from-push-notifications

/openapi/alerts.json post /v2/push/unsubscribe
Remove device from push notification delivery with support for app-specific or global unsubscription



# Verify Solana Authentication
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/verify-solana-authentication

/openapi/alerts.json post /v2/auth/solana/verify
Complete Solana wallet authentication by verifying signed message and receive JWT token for session access



# Verify Solana Transaction Authentication
Source: https://docs.dialect.to/api-reference/integrate-an-inbox/verify-solana-transaction-authentication

/openapi/alerts.json post /v2/auth/solana-tx/verify
Complete Solana wallet authentication by verifying signed transaction and receive JWT token



# Borrow
Source: https://docs.dialect.to/api-reference/jupiter/lend-borrow/borrow

/openapi/jupiter.json get /api/v0/lend/borrow/{vaultId}/{positionId}/borrow
Get available borrow actions for a position



# Borrow
Source: https://docs.dialect.to/api-reference/jupiter/lend-borrow/borrow-1

/openapi/jupiter.json post /api/v0/lend/borrow/{vaultId}/{positionId}/borrow
Execute a borrow transaction for the specified vault and amount



# Deposit
Source: https://docs.dialect.to/api-reference/jupiter/lend-borrow/deposit

/openapi/jupiter.json get /api/v0/lend/borrow/{vaultId}/deposit
Get available deposit actions for a token



# Deposit
Source: https://docs.dialect.to/api-reference/jupiter/lend-borrow/deposit-1

/openapi/jupiter.json post /api/v0/lend/borrow/{vaultId}/deposit
Execute a deposit transaction for the specified vault and amount



# Repay
Source: https://docs.dialect.to/api-reference/jupiter/lend-borrow/repay

/openapi/jupiter.json get /api/v0/lend/borrow/{vaultId}/{positionId}/repay
Get available repay actions for a position



# Repay
Source: https://docs.dialect.to/api-reference/jupiter/lend-borrow/repay-1

/openapi/jupiter.json post /api/v0/lend/borrow/{vaultId}/{positionId}/repay
Execute a repay transaction for the specified vault and amount



# Withdraw
Source: https://docs.dialect.to/api-reference/jupiter/lend-borrow/withdraw

/openapi/jupiter.json get /api/v0/lend/borrow/{vaultId}/{positionId}/withdraw
Get available withdraw actions for a token



# Withdraw
Source: https://docs.dialect.to/api-reference/jupiter/lend-borrow/withdraw-1

/openapi/jupiter.json post /api/v0/lend/borrow/{vaultId}/{positionId}/withdraw
Execute a withdraw transaction for the specified vault and amount



# Earn Deposit
Source: https://docs.dialect.to/api-reference/jupiter/lend-earn/earn-deposit

/openapi/jupiter.json get /api/v0/lend/earn/{vaultToken}/deposit
Get available deposit actions for a token



# Earn Deposit
Source: https://docs.dialect.to/api-reference/jupiter/lend-earn/earn-deposit-1

/openapi/jupiter.json post /api/v0/lend/earn/{vaultToken}/deposit
Execute a deposit transaction for the specified token and amount



# Earn Withdraw
Source: https://docs.dialect.to/api-reference/jupiter/lend-earn/earn-withdraw

/openapi/jupiter.json get /api/v0/lend/earn/{vaultToken}/withdraw
Get available withdraw actions for a token



# Earn Withdraw
Source: https://docs.dialect.to/api-reference/jupiter/lend-earn/earn-withdraw-1

/openapi/jupiter.json post /api/v0/lend/earn/{vaultToken}/withdraw
Execute withdraw transaction for the specified token and amount



# Swap Token
Source: https://docs.dialect.to/api-reference/jupiter/swap/swap-token

/openapi/jupiter.json get /api/v0/swap/{tokenPair}
Get available swap actions for a token pair



# Swap Token Amount
Source: https://docs.dialect.to/api-reference/jupiter/swap/swap-token-amount

/openapi/jupiter.json get /api/v0/swap/{tokenPair}/{amount}
Get swap action details for a specific token pair and amount



# Swap Token Amount
Source: https://docs.dialect.to/api-reference/jupiter/swap/swap-token-amount-1

/openapi/jupiter.json post /api/v0/swap/{tokenPair}/{amount}
Execute a swap transaction for the specified token pair and amount



# Borrow
Source: https://docs.dialect.to/api-reference/kamino/borrow/borrow-get

/openapi/kamino.json get /v0/lending/reserve/{market}/{reserve}/borrow
Get a blink for borrow operations on a reserve



# Borrow
Source: https://docs.dialect.to/api-reference/kamino/borrow/borrow-post

/openapi/kamino.json post /v0/lending/reserve/{market}/{reserve}/borrow
Execute a borrow operation



# Claim Rewards
Source: https://docs.dialect.to/api-reference/kamino/borrow/claim-rewards-get

/openapi/kamino.json get /v0/lending/reserve/{market}/{reserve}/claim-rewards
Get a blink for claiming rewards on a reserve



# Claim Rewards
Source: https://docs.dialect.to/api-reference/kamino/borrow/claim-rewards-post

/openapi/kamino.json post /v0/lending/reserve/{market}/{reserve}/claim-rewards
Execute a claim rewards operation



# Deposit
Source: https://docs.dialect.to/api-reference/kamino/borrow/deposit-get

/openapi/kamino.json get /v0/lending/reserve/{market}/{reserve}/deposit
Get a blink for deposit operations on a reserve



# Deposit
Source: https://docs.dialect.to/api-reference/kamino/borrow/deposit-post

/openapi/kamino.json post /v0/lending/reserve/{market}/{reserve}/deposit
Execute a deposit operation



# Repay
Source: https://docs.dialect.to/api-reference/kamino/borrow/repay-get

/openapi/kamino.json get /v0/lending/reserve/{market}/{reserve}/repay
Get a blink for repay operations on a reserve



# Repay
Source: https://docs.dialect.to/api-reference/kamino/borrow/repay-post

/openapi/kamino.json post /v0/lending/reserve/{market}/{reserve}/repay
Execute a repay operation



# Repay With Collateral
Source: https://docs.dialect.to/api-reference/kamino/borrow/repay-with-collateral-get

/openapi/kamino.json get /v0/lending/reserve/{market}/{reserve}/repay-with-collateral
Get a blink for repaying debt using collateral



# Repay With Collateral
Source: https://docs.dialect.to/api-reference/kamino/borrow/repay-with-collateral-post

/openapi/kamino.json post /v0/lending/reserve/{market}/{reserve}/repay-with-collateral
Execute a repay with collateral operation



# Withdraw
Source: https://docs.dialect.to/api-reference/kamino/borrow/withdraw-get

/openapi/kamino.json get /v0/lending/reserve/{market}/{reserve}/withdraw
Get a blink for withdraw operations on a reserve



# Withdraw
Source: https://docs.dialect.to/api-reference/kamino/borrow/withdraw-post

/openapi/kamino.json post /v0/lending/reserve/{market}/{reserve}/withdraw
Execute a withdraw operation



# Claim Farm Rewards
Source: https://docs.dialect.to/api-reference/kamino/farms/claim-rewards-get

/openapi/kamino.json get /v0/farms/{farmAddress}/claim-rewards
Get metadata for claiming Kamino farm rewards.



# Claim Farm Rewards
Source: https://docs.dialect.to/api-reference/kamino/farms/claim-rewards-post

/openapi/kamino.json post /v0/farms/{farmAddress}/claim-rewards
Generate a transaction to claim all rewards for a farm.



# Lend Vault Claim Rewards
Source: https://docs.dialect.to/api-reference/kamino/lend/claim-rewards-get

/openapi/kamino.json get /v0/lend/{vaultId}/claim-rewards
Get a blink for claiming rewards operations on a vault



# Lend Vault Claim Rewards
Source: https://docs.dialect.to/api-reference/kamino/lend/claim-rewards-post

/openapi/kamino.json post /v0/lend/{vaultId}/claim-rewards
Execute a claim rewards operation



# Lend Vault Deposit
Source: https://docs.dialect.to/api-reference/kamino/lend/deposit-get

/openapi/kamino.json get /v0/lend/{vaultId}/deposit
Get a blink for deposit operations on a vault



# Lend Vault Deposit
Source: https://docs.dialect.to/api-reference/kamino/lend/deposit-post

/openapi/kamino.json post /v0/lend/{vaultId}/deposit
Execute a deposit operation



# Lend Vault Withdraw
Source: https://docs.dialect.to/api-reference/kamino/lend/withdraw-get

/openapi/kamino.json get /v0/lend/{vaultId}/withdraw
Get a blink for withdraw operations on a vault



# Lend Vault Withdraw
Source: https://docs.dialect.to/api-reference/kamino/lend/withdraw-post

/openapi/kamino.json post /v0/lend/{vaultId}/withdraw
Execute a withdraw operation



# Leverage Close Position
Source: https://docs.dialect.to/api-reference/kamino/leverage/closeposition-get

/openapi/kamino.json get /v0/leverage/{marketAddress}/closePosition
Get metadata for closing a leverage position.



# Leverage Close Position
Source: https://docs.dialect.to/api-reference/kamino/leverage/closeposition-post

/openapi/kamino.json post /v0/leverage/{marketAddress}/closePosition
Generate a transaction for closing a leverage position.



# Leverage Open Position
Source: https://docs.dialect.to/api-reference/kamino/leverage/openposition-get

/openapi/kamino.json get /v0/leverage/{marketAddress}/openPosition
Get metadata for opening a leverage position.



# Leverage Open Position
Source: https://docs.dialect.to/api-reference/kamino/leverage/openposition-post

/openapi/kamino.json post /v0/leverage/{marketAddress}/openPosition
Generate a transaction for opening a leverage position.



# Leverage Setup
Source: https://docs.dialect.to/api-reference/kamino/leverage/setup-get

/openapi/kamino.json get /v0/leverage/{marketAddress}/setup
Get metadata for setting up leverage position (LUT creation).



# Leverage Setup
Source: https://docs.dialect.to/api-reference/kamino/leverage/setup-post

/openapi/kamino.json post /v0/leverage/{marketAddress}/setup
Generate transactions for setting up leverage position (LUT creation).



# Liquidity Vault Deposit
Source: https://docs.dialect.to/api-reference/kamino/liquidity/deposit-get

/openapi/kamino.json get /v0/liquidity/{vaultAddress}/deposit
Get metadata for depositing into a liquidity vault.



# Liquidity Vault Deposit
Source: https://docs.dialect.to/api-reference/kamino/liquidity/deposit-post

/openapi/kamino.json post /v0/liquidity/{vaultAddress}/deposit
Generate a transaction for depositing into a liquidity vault.



# Liquidity Vault Withdraw
Source: https://docs.dialect.to/api-reference/kamino/liquidity/withdraw-get

/openapi/kamino.json get /v0/liquidity/{vaultAddress}/withdraw
Get metadata for withdrawing from a liquidity vault.



# Liquidity Vault Withdraw
Source: https://docs.dialect.to/api-reference/kamino/liquidity/withdraw-post

/openapi/kamino.json post /v0/liquidity/{vaultAddress}/withdraw
Generate a transaction for withdrawing from a liquidity vault.



# Multiply Deposit
Source: https://docs.dialect.to/api-reference/kamino/multiply/deposit-get

/openapi/kamino.json get /v0/multiply/{marketAddress}/deposit
Get metadata for depositing with leverage/multiply.



# Multiply Deposit
Source: https://docs.dialect.to/api-reference/kamino/multiply/deposit-post

/openapi/kamino.json post /v0/multiply/{marketAddress}/deposit
Generate a transaction for depositing with leverage/multiply.



# Multiply Setup
Source: https://docs.dialect.to/api-reference/kamino/multiply/setup-get

/openapi/kamino.json get /v0/multiply/{marketAddress}/setup
Get metadata for setting up multiply position (LUT creation).



# Multiply Setup
Source: https://docs.dialect.to/api-reference/kamino/multiply/setup-post

/openapi/kamino.json post /v0/multiply/{marketAddress}/setup
Generate transactions for setting up multiply position (LUT creation).



# Multiply Withdraw
Source: https://docs.dialect.to/api-reference/kamino/multiply/withdraw-get

/openapi/kamino.json get /v0/multiply/{marketAddress}/withdraw
Get metadata for withdrawing from multiply position.



# Multiply Withdraw
Source: https://docs.dialect.to/api-reference/kamino/multiply/withdraw-post

/openapi/kamino.json post /v0/multiply/{marketAddress}/withdraw
Generate a transaction for withdrawing from multiply position.



# Deposit
Source: https://docs.dialect.to/api-reference/lulo/deposit/deposit-get

/openapi/lulo.json get /v0/deposit/{token}/{type}
Get metadata for depositing a token into Lulo.



# Deposit
Source: https://docs.dialect.to/api-reference/lulo/deposit/deposit-post

/openapi/lulo.json post /v0/deposit/{token}/{type}
Generate a transaction for depositing a token into Lulo.



# Complete Regular Withdrawal
Source: https://docs.dialect.to/api-reference/lulo/withdraw/complete-get

/openapi/lulo.json get /v0/withdraw/{token}/regular/complete
Get metadata for withdrawing a token from Lulo Regular after cooldown period.



# Complete Regular Withdrawal
Source: https://docs.dialect.to/api-reference/lulo/withdraw/complete-post

/openapi/lulo.json post /v0/withdraw/{token}/regular/complete
Generate a transaction for withdrawing a token from Lulo Regular after cooldown period.



# Withdraw
Source: https://docs.dialect.to/api-reference/lulo/withdraw/withdraw-get

/openapi/lulo.json get /v0/withdraw/{token}/{type}
Get metadata for withdrawing a token from Lulo.



# Withdraw
Source: https://docs.dialect.to/api-reference/lulo/withdraw/withdraw-post

/openapi/lulo.json post /v0/withdraw/{token}/{type}
Generate a transaction for withdrawing a token from Lulo.



# Delete Email Channel
Source: https://docs.dialect.to/api-reference/manage-channels/delete-email-channel

/openapi/alerts.json post /v2/channel/email/delete
Delete email channel for a subscriber



# Delete Telegram Channel
Source: https://docs.dialect.to/api-reference/manage-channels/delete-telegram-channel

/openapi/alerts.json post /v2/channel/telegram/delete
Delete telegram channel for a subscriber



# Get Channels
Source: https://docs.dialect.to/api-reference/manage-channels/get-channels

/openapi/alerts.json get /v2/channels
Get user's channels and channel subscriptions



# Prepare Email Channel
Source: https://docs.dialect.to/api-reference/manage-channels/prepare-email-channel

/openapi/alerts.json post /v2/channel/email/prepare
Prepare email channel for a subscriber



# Prepare Telegram Channel
Source: https://docs.dialect.to/api-reference/manage-channels/prepare-telegram-channel

/openapi/alerts.json post /v2/channel/telegram/prepare
Prepare telegram channel for a subscriber



# Resend Email Verification
Source: https://docs.dialect.to/api-reference/manage-channels/resend-email-verification

/openapi/alerts.json post /v2/channel/email/resend
Resend email verification for a subscriber



# Verify Email Channel
Source: https://docs.dialect.to/api-reference/manage-channels/verify-email-channel

/openapi/alerts.json post /v2/channel/email/verify
Verify email channel for a subscriber



# Lend Deposit Token
Source: https://docs.dialect.to/api-reference/marginfi/lend/deposit-get

/openapi/marginfi.json get /v0/lend/{tokenSymbol}/deposit
Get metadata for depositing a token into a MarginFi pool.



# Lend Deposit Token
Source: https://docs.dialect.to/api-reference/marginfi/lend/deposit-post

/openapi/marginfi.json post /v0/lend/{tokenSymbol}/deposit
Generate a transaction for depositing a token into a MarginFi pool.



# Lend Withdraw Token
Source: https://docs.dialect.to/api-reference/marginfi/lend/withdraw-get

/openapi/marginfi.json get /v0/lend/{tokenSymbol}/withdraw
Get metadata for withdrawing a token from a MarginFi pool.



# Lend Withdraw Token
Source: https://docs.dialect.to/api-reference/marginfi/lend/withdraw-post

/openapi/marginfi.json post /v0/lend/{tokenSymbol}/withdraw
Generate a transaction for withdrawing a token from a MarginFi pool.



# Get historical market snapshots
Source: https://docs.dialect.to/api-reference/markets/get-historical-market-snapshots

/openapi/markets.json get /v0/markets/history
Fetch market snapshots within a time range for one or more markets. Optionally interpolate to a uniform time grid.



# List all markets
Source: https://docs.dialect.to/api-reference/markets/list-all-markets

/openapi/markets.json get /v0/markets
Returns real-time market data from supported protocols, such as Jupiter, Kamino, MarginFi, Lulo and many more. For more information, please check our [Protocol Support Roadmap](/markets/supported-protocols).

Note: Some providers (e.g. Kamino) may return large responses with 100+ markets. For better performance in the API playground, consider filtering by both `type` and `provider` parameters.



# List all markets grouped by type
Source: https://docs.dialect.to/api-reference/markets/list-all-markets-grouped-by-type

/openapi/markets.json get /v0/marketsByType
Supported providers: MarginFi Lending, Kamino Lending, Kamino Multiply, Kamino Leverage, Lulo. Temporarily without `prediction` type.



# Launch Success
Source: https://docs.dialect.to/api-reference/meteora/dbc/launch-success

/openapi/meteora.json post /v0/bonding-curve/success
Action-chained endpoint called automatically after a successful Launch Token transaction. The previous response provides a `links.next.href` containing the mint, ticker, and name as query params. Returns a success blink with a link to trade the newly launched token.



# Launch Token
Source: https://docs.dialect.to/api-reference/meteora/dbc/launch-token-get

/openapi/meteora.json get /v0/bonding-curve/launch-token
Get a blink for launching a token on Meteora Dynamic Bonding Curve



# Launch Token
Source: https://docs.dialect.to/api-reference/meteora/dbc/launch-token-post

/openapi/meteora.json post /v0/bonding-curve/launch-token
Launch a token on Meteora Dynamic Bonding Curve



# Add Liquidity
Source: https://docs.dialect.to/api-reference/meteora/dlmm/add-liquidity-get

/openapi/meteora.json get /v0/dlmm/{dlmmPool}/add-liquidity
Get a blink for adding liquidity to a DLMM pool



# Add Liquidity
Source: https://docs.dialect.to/api-reference/meteora/dlmm/add-liquidity-post

/openapi/meteora.json post /v0/dlmm/{dlmmPool}/add-liquidity
Add liquidity to a DLMM pool



# Remove Liquidity
Source: https://docs.dialect.to/api-reference/meteora/dlmm/remove-liquidity-get

/openapi/meteora.json get /v0/dlmm/{dlmmPool}/remove-liquidity
Get a blink for removing liquidity from a DLMM pool



# Remove Liquidity
Source: https://docs.dialect.to/api-reference/meteora/dlmm/remove-liquidity-post

/openapi/meteora.json post /v0/dlmm/{dlmmPool}/remove-liquidity
Remove liquidity from a DLMM pool



# Add Liquidity
Source: https://docs.dialect.to/api-reference/orca/pools/add-liquidity-get

/openapi/orca.json get /v0/pools/positions/{positionAddress}/add-liquidity
Get a blink for adding liquidity to a position



# Add Liquidity
Source: https://docs.dialect.to/api-reference/orca/pools/add-liquidity-post

/openapi/orca.json post /v0/pools/positions/{positionAddress}/add-liquidity
Add liquidity to a position.



# Close Position
Source: https://docs.dialect.to/api-reference/orca/pools/close-position-get

/openapi/orca.json get /v0/pools/positions/{positionAddress}/close-position
Get a blink for closing a position



# Close Position
Source: https://docs.dialect.to/api-reference/orca/pools/close-position-post

/openapi/orca.json post /v0/pools/positions/{positionAddress}/close-position
Close a position and withdraw all liquidity.



# Open Position
Source: https://docs.dialect.to/api-reference/orca/pools/open-position-get

/openapi/orca.json get /v0/pools/{tokenA}/{tokenB}/open-position
Get a blink for opening a position



# Open Position
Source: https://docs.dialect.to/api-reference/orca/pools/open-position-post

/openapi/orca.json post /v0/pools/{tokenA}/{tokenB}/open-position
Open position. If lowerPrice and upperPrice are provided, open a position with a specific price range. If not, open a full range position.



# Remove Liquidity
Source: https://docs.dialect.to/api-reference/orca/pools/remove-liquidity-get

/openapi/orca.json get /v0/pools/positions/{positionAddress}/remove-liquidity
Get a blink for removing liquidity from a position



# Remove Liquidity
Source: https://docs.dialect.to/api-reference/orca/pools/remove-liquidity-post

/openapi/orca.json post /v0/pools/positions/{positionAddress}/remove-liquidity
Remove liquidity from a position.



# Get historical position snapshots
Source: https://docs.dialect.to/api-reference/positions/get-historical-position-snapshots

/openapi/markets.json get /v0/positions/history
Fetch position snapshots within a time range for a wallet address. Optionally interpolate using Birdeye price data.



# Get PnL data for wallet positions
Source: https://docs.dialect.to/api-reference/positions/get-pnl-data-for-wallet-positions

/openapi/markets.json get /v0/positions/pnl
Computes realized and unrealized PnL for all pnl-able positions (currently DFlow prediction only), including closed positions.



# List all market positions by wallet address
Source: https://docs.dialect.to/api-reference/positions/list-all-market-positions-by-wallet-address

/openapi/markets.json get /v0/positions/owners
Supported providers & markets: Kamino Lending, Lulo.



# Add Liquidity
Source: https://docs.dialect.to/api-reference/raydium/amm/add-liquidity-get

/openapi/raydium.json get /v0/amm/{poolId}/add-liquidity
Get a blink for adding liquidity to a Standard AMM pool



# Add Liquidity
Source: https://docs.dialect.to/api-reference/raydium/amm/add-liquidity-post

/openapi/raydium.json post /v0/amm/{poolId}/add-liquidity
Add liquidity to a Standard AMM pool



# Remove Liquidity
Source: https://docs.dialect.to/api-reference/raydium/amm/remove-liquidity-get

/openapi/raydium.json get /v0/amm/{poolId}/remove-liquidity
Get a blink for removing liquidity from a Standard AMM pool



# Remove Liquidity
Source: https://docs.dialect.to/api-reference/raydium/amm/remove-liquidity-post

/openapi/raydium.json post /v0/amm/{poolId}/remove-liquidity
Remove liquidity from a Standard AMM pool



# Add Liquidity
Source: https://docs.dialect.to/api-reference/raydium/clmm/add-liquidity-get

/openapi/raydium.json get /v0/clmm/{poolId}/add-liquidity
Get a blink for adding liquidity to a CLMM pool



# Add Liquidity
Source: https://docs.dialect.to/api-reference/raydium/clmm/add-liquidity-post

/openapi/raydium.json post /v0/clmm/{poolId}/add-liquidity
Add liquidity to a CLMM pool



# Remove Liquidity
Source: https://docs.dialect.to/api-reference/raydium/clmm/remove-liquidity-get

/openapi/raydium.json get /v0/clmm/{poolId}/remove-liquidity
Get a blink for removing liquidity from a CLMM pool



# Remove Liquidity
Source: https://docs.dialect.to/api-reference/raydium/clmm/remove-liquidity-post

/openapi/raydium.json post /v0/clmm/{poolId}/remove-liquidity
Remove liquidity from a CLMM pool



# RAY Stake
Source: https://docs.dialect.to/api-reference/raydium/farm/stake-get

/openapi/raydium.json get /v0/farm/RAY/stake
Stake RAY in Raydium Farm product



# RAY Stake
Source: https://docs.dialect.to/api-reference/raydium/farm/stake-post

/openapi/raydium.json post /v0/farm/RAY/stake
Stake RAY in Raydium Farm product. Either percentage or amount is required.



# RAY Unstake
Source: https://docs.dialect.to/api-reference/raydium/farm/unstake-get

/openapi/raydium.json get /v0/farm/RAY/unstake
Unstake RAY in Raydium Farm product



# RAY Unstake
Source: https://docs.dialect.to/api-reference/raydium/farm/unstake-post

/openapi/raydium.json post /v0/farm/RAY/unstake
Unstake RAY in Raydium Farm product. Either percentage or amount is required.



# Deposit
Source: https://docs.dialect.to/api-reference/save/lending/deposit-get

/openapi/save.json get /v0/lending/{marketAddress}/reserves/{reserve}/deposit
Get a blink to deposit a token into protected or boosted deposits



# Deposit
Source: https://docs.dialect.to/api-reference/save/lending/deposit-post

/openapi/save.json post /v0/lending/{marketAddress}/reserves/{reserve}/deposit
Deposit a specific amount of a token to a reserve



# Withdraw
Source: https://docs.dialect.to/api-reference/save/lending/withdraw-get

/openapi/save.json get /v0/lending/{marketAddress}/reserves/{reserve}/withdraw
Get a blink to withdraw a token from a reserve



# Withdraw
Source: https://docs.dialect.to/api-reference/save/lending/withdraw-post

/openapi/save.json post /v0/lending/{marketAddress}/reserves/{reserve}/withdraw
Withdraw a specific amount of a token from a reserve



# Get App Subscribers
Source: https://docs.dialect.to/api-reference/send-alerts/get-app-subscribers

/openapi/alerts.json get /v2/{appId}/subscribers
Retrieve paginated list of all subscribers for application management with filtering and pagination support



# Get App Topics
Source: https://docs.dialect.to/api-reference/send-alerts/get-app-topics

/openapi/alerts.json get /v2/{appId}/topics
Retrieve all available alert topics for a specific application with detailed topic information including names, descriptions, and slugs for topic-based alert categorization



# Send Alert
Source: https://docs.dialect.to/api-reference/send-alerts/send-alert

/openapi/alerts.json post /v2/{appId}/send
Send alert to one subscriber, multiple subscribers, or all with rich content support including images, actions, and custom data



# Send Batch Alerts
Source: https://docs.dialect.to/api-reference/send-alerts/send-batch-alerts

/openapi/alerts.json post /v2/{appId}/send-batch
Send multiple alerts in a single request for improved performance with up to 500 alerts per batch



# Transfer Token
Source: https://docs.dialect.to/api-reference/solana/transfer/transfer-get

/openapi/solana.json get /v0/transfer/{token}
Get a blink for transferring a token



# Transfer Token
Source: https://docs.dialect.to/api-reference/solana/transfer/transfer-post

/openapi/solana.json post /v0/transfer/{token}
Transfer any Solana tokens to any address



# Introduction
Source: https://docs.dialect.to/blinks/blinks-client/index

Blinks are distributable experiences that can be embedded anywhere a link can exist. They offer a modern approach to service integration, replacing traditional SDKs with a more streamlined, maintainable solution.

The Blinks Client provides [frontend components](/blinks/blinks-client/integrate/ui-components/blinks) and [headless integration](/blinks/blinks-client/integrate/headless/index) options for rendering and interacting with blinks in your applications.

<img alt="Blinks Integration in a Website" />

### Key Benefits

* **Simple Integration**: Other developers can integrate your service in seconds while you maintain ownership of the blink
* **Consistent Experience**: Ensure your service implementation follows your design principles and best practices
* **Centralized Updates**: Changes made to your blink are automatically reflected everywhere it's served, eliminating SDK update cycles
* **User-Friendly Interface**: Blinks can unfurl to present an intuitive UI, encouraging user engagement through simple button clicks

## Integration Options

<CardGroup>
  <Card title="UI Components" icon="puzzle-piece" href="/blinks/blinks-client/integrate/ui-components/blinks">
    Pre-built React components for easy integration with minimal setup. Perfect for React applications that want complete Blink functionality out of the box.
  </Card>

  <Card title="Headless Integration" icon="code" href="/blinks/blinks-client/integrate/headless/index">
    For developers who need maximum flexibility and control. Use HTTP endpoints to interact with Blinks programmatically, enabling custom implementations and integrations with AI agents or backend systems.
  </Card>

  <Card title="Chrome Extension" icon="chrome" href="/blinks/blinks-client/integrate/chrome/index">
    Integrate Blinks directly into browser experiences, allowing users to interact with blockchain actions from any website.
  </Card>
</CardGroup>

## Testing

For testing blink unfurling, we recommend you to use either our [dial.to](https://dial.to) website or our [starters](/blinks/blinks-starters/index) which also have a blink client pre-configured.

## Non-React Integration

Using a different tech stack? Reach out to us at [hello@dialect.to](mailto:hello@dialect.to) to discuss integration options for non-React codebases.


# Chrome Extension
Source: https://docs.dialect.to/blinks/blinks-client/integrate/chrome/index

Integrate Blinks directly into browser experiences, allowing users to interact with blockchain actions from any website.

This section is for Chrome extension developers who want to add Blinks to third party sites like Twitter. If you're interested in Native blink support check out our [React SDK](https://www.npmjs.com/package/@dialectlabs/blinks) or [React Native SDK](https://www.npmjs.com/package/@dialectlabs/blinks-react-native).

<img alt="Chrome extension showing Blinks integration on Twitter" />

```javascript theme={null}
// contentScript.ts
import { setupTwitterObserver } from "@dialectlabs/blinks/ext/twitter";
import { ActionConfig, ActionContext } from "@dialectlabs/blinks";

// your RPC_URL is used to create a connection to confirm the transaction after action execution
setupTwitterObserver(new ActionConfig(RPC_URL, {
  signTransaction: async (tx: string, context: ActionContext) => { ... },
  signMessage(data: string | SignMessageData, context: ActionContext) { ... },
  connect: async (context: ActionContext) => { ... }
}))

// or

import { type ActionAdapter } from "@dialectlabs/blinks";

class MyActionAdapter implements ActionAdapter {
  get metadata() { ... }
  async signTransaction(tx: string, context: ActionContext) { ... }
  async connect(context: ActionContext) { ... }
  async confirmTransaction(sig: string, context: ActionContext) { ... }
  async signMessage(data: string | SignMessageData, context: ActionContext) { ... }
}

setupTwitterObserver(new MyActionAdapter());
```

## Action Adapter & Multichain Compatibility

After implementation of [sRFC 31](https://forum.solana.com/t/srfc-31-compatibility-of-blinks-and-actions/1892), action developers can specify a target blockchain for an action by including metadata in responses. The action metadata is accessible within the `ActionContext` across `ActionAdapter` functions.

Chrome extension developers can also specify supported blockchains by defining them within the `ActionAdapter`. Additionally, other functions can be implemented to handle the action's blockchain based on the `ActionContext`.

For backward compatibility, the absence of blockchain IDs should be interpreted by Blink clients as actions targeting the Solana mainnet.

```typescript theme={null}
import {
  ActionAdapter,
  ActionAdapterMetadata,
  BlockchainIds,
  SignMessageData
} from '@dialectlabs/blinks';

class MyActionAdapter implements ActionAdapter {
  get metadata() {
    return {
      // the IDs are CAIP-2 compatible strings
      supportedBlockchainIds: [BlockchainIds.SOLANA_MAINNET, BlockchainIds.ETHEREUM_MAINNET],
    };
  }
  async signTransaction(tx: string, context: ActionContext) {
    const actionBlockchainIds = context.action.metadata.blockchainIds;
    if (
      !actionBlockchainIds ||
      actionBlockchainIds.includes(BlockchainIds.SOLANA_MAINNET)
    ) {
      // handle solana mainnet
      return;
    }
    if (actionBlockchainIds.includes(BlockchainIds.ETHEREUM_MAINNET)) {
      // handle ethereum mainnet
    }
  }
  async connect(context: ActionContext) { ... }
  async confirmTransaction(sig: string, context: ActionContext) { ... }
  async signMessage(data: string | SignMessageData, context: ActionContext) { ... }
}
```


# Headless Integration
Source: https://docs.dialect.to/blinks/blinks-client/integrate/headless/index

Learn how to interact with Blinks via pure REST HTTP.

<Tip>
  For the fastest solution integrating blinks, consider using our [UI Component](/blinks/blinks-client/integrate/ui-components/) libraries, available for both web and mobile.

  **Using these libraries can reduce your integration time by up to 99%.**
</Tip>

Headless blink integrations are perfect for developers who want pure data fetching without UI constraints. You get direct API access and can build your own interfaces and implementations from scratch.

Headless integration is also ideal for integration into more complex systems, such as AI agents.

In the examples below, we'll walk you through the basics and all available endpoints, helping you determine which endpoint best suits your use case.

## Blink Client Key

Before using our APIs, we recommend requesting a client key. A client key is a unique identifier used to register your blink in the [dashboard](https://dashboard.dialect.to/). This registration gives you access to:

* High-performance caching solutions
* Customized metadata
* Individualized status messages (`onSuccess`, `onFailure`, ...)
* Analytics

These features enable you to build a truly unique experience for your users.

To get your client key, please sign up for our [dashboard](https://dashboard.dialect.to/). In our examples and API documentation, the client key may be referred to as `YOUR_SECRET_TOKEN`.

<Note>
  The `X-Blink-Client-Key` header is optional. You can use our API endpoints without a client key, but you'll miss out on the features mentioned above.
</Note>

## Blink Data Types

Dialect's APIs provide three endpoints for fetching blink data: `Blink`, `BlinkPreview`, and `BlinkDataTable`.

<img alt="Blink UI Components" />

The `BlinkPreview` allows you to display a preview version of the blink with its own title, description, and image. It can be used for marketing purposes or in cases where you only want to render a preview without needing the full blink data.

The `Blink` endpoint contains all blink-related data, including its actions and the BlinkPreview. Use this API when you plan to interact with the blink.

**It is highly recommended to use the Dialect API when fetching a blink to benefit from all the additional features our SaaS platform offers.**

In the following example, we'll use the stake blink from Jito to guide you through the different API requests.

### `GET` Requests

The `GET` endpoint returns a `JSON` object that renders the blink or provides blink-relevant data, such as the `BlinkDataTable`.

#### Fetching a `Blink`

A `Blink` contains the complete, interactive data structure. It includes all necessary information to display and interact with a `Blink`, including its current state, possible actions, and related data.

This is the primary structure you'll work with when implementing blink functionality in your application.

<img alt="Image of a Blink incl. Blink Data Table and Extended Description" />

There are no strict requirements for image dimensions, but we recommend using either 16:9 or 1:1 aspect ratios.

```bash theme={null}
# CURL example to fetch a blink
# Note: The X-Blink-Client-Key header is optional but recommended

curl 'https://api.dial.to/v1/blink?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake' \
  --header 'X-Blink-Client-Key: YOUR_SECRET_TOKEN'
```

The above command will return a `JSON` object that can be used to render the blink.

```json theme={null}
{
  "type": "action",
  "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/6cc758de-394c-466f-15ee-295224bc8300/public",
  "label": "Convert to JitoSOL",
  "title": "Stake SOL to Earn ≈ 8.56% APY",
  "description": "Boost your yield when you stake with Jito.",
  "links": {
    "actions": [
      {
        "type": "transaction",
        "label": "25%",
        "href": "https://api.dial.to/v1/blink?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake%2Fpercentage%2F25%3F_bin%3D83308537-b8a4-4225-acd7-9269d79940a7"
      },
      {
        "type": "transaction",
        "label": "50%",
        "href": "https://api.dial.to/v1/blink?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake%2Fpercentage%2F50%3F_bin%3D83308537-b8a4-4225-acd7-9269d79940a7"
      },
      {
        "type": "transaction",
        "label": "100%",
        "href": "https://api.dial.to/v1/blink?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake%2Fpercentage%2F100%3F_bin%3D83308537-b8a4-4225-acd7-9269d79940a7"
      },
      {
        "type": "transaction",
        "href": "https://api.dial.to/v1/blink?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake%2Famount%2F{amount}%3F_bin%3D83308537-b8a4-4225-acd7-9269d79940a7",
        "label": "Convert to JitoSOL",
        "parameters": [
          {
            "name": "amount",
            "label": "Custom SOL amount"
          }
        ]
      }
    ],
    "dataTable": "https://api.dial.to/v1/blink-data-table?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake%3F_bin%3D83308537-b8a4-4225-acd7-9269d79940a7"
  },
  "context": {
    "category": "Liquid Staking Token",
    "url": "https://jito.dial.to/stake?_bin=83308537-b8a4-4225-acd7-9269d79940a7",
    "websiteUrl": "https://jito.network",
    "provider": {
      "name": "Jito",
      "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/59ed70c8-7fe7-437f-a149-a1ef3eb02500/public"
    }
  },
  "preview": {
    "title": "Stake SOL to Earn",
    "description": "Boost your yield when you stake with Jito.",
    "image": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/6cc758de-394c-466f-15ee-295224bc8300/public",
    "cta": "Stake",
    "context": {
      "category": "Liquid Staking Token",
      "url": "https://jito.dial.to/stake?_bin=83308537-b8a4-4225-acd7-9269d79940a7",
      "websiteUrl": "https://jito.network",
      "provider": {
        "name": "Jito",
        "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/59ed70c8-7fe7-437f-a149-a1ef3eb02500/public"
      }
    }
  },
  "extendedDescription": "## Why stake with Jito?\nStake your SOL and receive JitoSOL, which increases in value over time. You can use JitoSOL in DeFi protocols to earn additional rewards. Later, swap it back for your original deposit plus the accumulated earnings.    \n\n- **Higher rewards on average** Stake your SOL and receive JitoSOL, which increases in value over time. You can use JitoSOL in DeFi protocols to earn additional rewards. Later, swap it back for your original deposit plus the accumulated earnings.\n- **More secure and decentralized** Liquid staking with Jito strengthens Solana's network by distributing stakes across multiple validators, lowering the risk associated with validators that have low uptime."
}
```

To see the full data schema and test your API requests, checkout our [Blink API](https://api.dial.to/docs#tag/blink/GET/v1/blink) doc.

#### Fetching a `BlinkDataTable`

In addition to the `Blink` and `BlinkPreview` endpoints, we offer a `BlinkDataTable` endpoint. This can be used to highlight important information for your users, such as APY or balances.

Because `BlinkDataTables` are often compute-intensive, they have their own endpoint. This separation allows you to fetch them only when needed.

<img alt="Image of a Blink Data Table" />

```bash theme={null}
# CURL example to fetch a data table
# Note: The X-Blink-Client-Key header is optional but recommended

curl 'https://api.dial.to/v1/blink-data-table?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake' \
  --header 'X-Blink-Client-Key: YOUR_SECRET_TOKEN'
```

```json theme={null}
{
  "rows": [
    {
      "key": "apy",
      "title": "APY",
      "value": "8.56%"
    },
    {
      "key": "rate",
      "title": "Rate",
      "value": "1 JitoSOL ≈ 1.18 SOL"
    }
  ],
  "links": {
    "blink": "https://api.dial.to/v1/blink?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake%3F_bin%3D83308537-b8a4-4225-acd7-9269d79940a7",
    "preview": "https://api.dial.to/v1/blink-preview?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake%3F_bin%3D83308537-b8a4-4225-acd7-9269d79940a7"
  },
  "context": {
    "category": "Liquid Staking Token",
    "url": "https://jito.dial.to/stake?_bin=83308537-b8a4-4225-acd7-9269d79940a7",
    "websiteUrl": "https://jito.network",
    "provider": {
      "name": "Jito",
      "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/59ed70c8-7fe7-437f-a149-a1ef3eb02500/public"
    }
  }
}
```

To see the full data schema and test your API requests, checkout our [BlinkDataTable API](https://api.dial.to/docs#tag/blink-data-table) docs.

#### Fetching a `BlinkPreview`

`BlinkPreview` is a small, static set of data used to display relevant information about the blink. Consider it an opportunity to use marketing language and render a preview instead of the full blink - useful for lists or websites that don't yet unfurl blinks.

It is recommended to use a separate 16:9 image for this preview.

<img alt="Image of a Preview Blink" />

```bash theme={null}
# CURL example to fetch a blink preview
# Note: The X-Blink-Client-Key header is optional but recommended

curl 'https://api.dial.to/v1/blink-preview?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake' \
  --header 'X-Blink-Client-Key: YOUR_SECRET_TOKEN'
```

```json theme={null}
{
  "title": "Stake SOL to Earn",
  "description": "Boost your yield when you stake with Jito.",
  "image": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/6cc758de-394c-466f-15ee-295224bc8300/public",
  "cta": "Stake",
  "context": {
    "category": "Liquid Staking Token",
    "url": "https://jito.dial.to/stake?_bin=83308537-b8a4-4225-acd7-9269d79940a7",
    "websiteUrl": "https://jito.network",
    "provider": {
      "name": "Jito",
      "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/59ed70c8-7fe7-437f-a149-a1ef3eb02500/public"
    }
  },
  "links": {
    "blink": "https://api.dial.to/v1/blink?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake%3F_bin%3D83308537-b8a4-4225-acd7-9269d79940a7",
    "dataTable": "https://api.dial.to/v1/blink-data-table?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake%3F_bin%3D83308537-b8a4-4225-acd7-9269d79940a7"
  }
}
```

To see the full data schema and test your API requests, checkout our [BlinkPreview API](https://api.dial.to/docs#tag/blink-preview/GET/v1/blink-preview) docs.

### `POST` requests

Once a user clicks on a button, the blink will send a POST request to your backend. This request always contains the wallet address (account) of the user. Additional data can be sent via the URL, e.g., by using URL parameters.

Example URL for POST: `https://jito.dial.to/stake/percentage/25`

In this blink, we use our example from the Jito staking blink again. Please note that the URL has changed from `/stake` (GET endpoint) to `/stake/percentage` (POST endpoint). The number 25 indicates that 25% of the user's SOL balance will be staked.

There are no specific requirements for the design of your link structure or endpoints. Most blinks use the same endpoint for their GET and POST requests and utilize URL parameters to add extra values.

```bash theme={null}
# CURL example of a blink POST request
# Note: The X-Blink-Client-Key header is optional but recommended

curl 'https://api.dial.to/v1/blink?apiUrl=https%3A%2F%2Fjito.dial.to%2Fstake%2Fpercentage%2F25' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Blink-Client-Key: YOUR_SECRET_TOKEN' \
  --data '{
  "type": "transaction",
  "account": "YOUR_WALLET_ADDRESS"
}'
```

If everything is correct, the blink provider will send a transaction to the frontend that can be signed by the user.

Creating a ready-to-sign transaction in the backend and sending this transaction to the frontend is one of the superpowers of building with blinks. This approach gives blink builders the power to implement their services in the way they know works best, thereby:

* Reducing the chances of incorrect implementations
* Providing a single point of maintenance
* Ensuring full control over the blink

Blink clients who want to integrate new services for their users can simply fetch a blink, eliminating the need for client-side SDKs or complex implementation scenarios.

Blinks are also the preferred way for teams who want to integrate their services into AI agent kits.

The blink provider from the example above will return the following JSON:

```json theme={null}
{
  "type": "transaction",
  "transaction": "AgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD4knXJvK4GgcN8HYwIVt6A8NrRxNXjC5mFEnmwb792Qix9U/nPzDt3Z/Vnlk91cpfThQNi9pfbCuGivaWm4+sAgAIACA9XZuSyYgzMaVVNxyidlVd0xIghrnt1V1Ew/3RDhg7zzEKSLPDzeRJEULXXPQDyPnR1Y9zFMLVG2mZPp8vNsNaUhSx40kphsfcZUjodpnaevz9/Klx/uuv1NoS2sqRRvQ780UHpgyyvEK2RdJXKDycbWyk81HAn6nNwB+1A6zmgvQSKPgjDtJW+F/RUJ9ib7FuAx+JpXBhk12dD2zm+00bWnqdo/t9kTIqum44hiK3Qa8VQ+/cWyCK5zmPHeD2VLh8J5qP+7PmQMuHB32uXItyzY057jjRAk2vDSwzByOtSHwMGRm/lIRcy/+ytunLDm+e8jOW7xfcSayxDmzpAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACMlyWPTiSJ8bs9ECkUjg2DC1oTmdr/EIQEjnvY2+n4WQbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCpBoFO1Mr2ihdGcv2shgMaY+hOoV76HUS3IpP229sAFlBU5Z4kwFGooUp7HpeX8OEs36dJAhZlMZWmpRKm8WZgKwu8D8C7R8ovdMQRLpSrE8+jxjTl3BfqywPNGiPNfnh8JSDzG2mhpKm2CAy/ETfbs0d85ZDqeBK+3Jhsm/SZ7/fJXGOTQWmZ5fiSAUZMu8ODn5nPNLKk0UpjcoeM/H5gcwUHAAkDIJpNAAAAAAAIAgABDAIAAAA4UU0AAAAAAAkGAAIAAwgKAQELCgQMBQECBgIDCAoJDjhRTQAAAAAADQEOBWJsaW5rAA==",
  "dialectExperimental": {
    "reference": "3VwE64hHjQS4oBGXyWuWSe1jx8gfnDiy1PvfFLV3pbBt"
  }
}
```

To see the full data schema and test your API requests, checkout our [Blink POST API](https://api.dial.to/docs#tag/blink/POST/v1/blink) docs.

### Multi-Step Blinks: Action Chaining

<img alt="Action chaining example flow" />

Action Chaining allows you to create complex workflows by connecting multiple blink actions in a sequential order. Instead of handling single, isolated actions, you can orchestrate a series of interconnected steps to create more complex user experiences.

Our SDKs are the recommended way to implement action chaining as they handle the complexity for you.

### Handling Multiple Transactions (Experimental)

<Warning>
  **Experimental Feature**: Multiple transactions are not part of the official Solana Actions specification and are not supported by Dialect's official Blinks libraries. This is an experimental extension for specific use cases that require multiple transactions to be executed.
</Warning>

Some complex DeFi operations require multiple transactions to be executed sequentially. When a blink provider needs to return multiple transactions, the response will use `type: "transactions"` instead of `type: "transaction"`:

```json theme={null}
{
  "type": "transactions",
  "transactions": [
    "transaction_1",
    "transaction_2",
    "transaction_3"
  ],
  "mode": "sequential",
  "dialectExperimental": {
    "reference": "transaction_reference_id"
  }
}
```

**Implementation Requirements**

When handling multiple transactions, clients must:

1. **Execute sequentially**: Sign and submit each transaction in order, waiting for confirmation before proceeding
2. **Update cache** (recommended): Refresh account state and balances between transactions to ensure accurate data
3. **Handle confirmations**: Wait for each transaction to be confirmed on-chain before signing the next
4. **Update Blockhash**: Fetch a fresh recent blockhash before signing the next transaction
5. **Manage failures**: If any transaction fails, stop the sequence and handle the error appropriately

<Note>
  Transaction signing is the client's responsibility. Dialect provides the transactions ready for signing, but implementing wallet interaction and signature collection is handled by your application using standard Solana libraries such as `@solana/web3.js`, `@solana/kit`, or `gill`. (Single transactions can be handled by the blink client directly)
</Note>

For more details on how providers implement multiple transactions, see the [provider documentation](/blinks/blinks-provider/advanced/multiple-transactions).

### Input types

Blinks can be more than just one-click button actions. In fact, they can become really powerful when you add multiple inputs.

If you look at our [Standard Blinks Library (SBL)](/standard-blinks-library), you will find many blinks that feature radio buttons, dropdown menus, checkboxes, and much more. This allows you to build full-fledged forms or even games that run entirely on blinks.

<img alt="Blink Forms" />

If you want to learn more about the input types that you can use for your blink, check out our forms section.

### Wallets and Apps

As mentioned in the `POST` section, blinks offer a fast and secure way to implement new services into your app, and implementation becomes even easier when using our [UI component kits](/blinks/blinks-client/integrate/ui-components/).

Many wallets have already chosen to use blinks instead of implementing each service for their users themselves.

<img alt="Blink integration in apps and wallets" />

The blink UI component kits are available for React and React Native. Using our [dashboard](https://dashboard.dialect.to/), you can remotely manage your app's blinks: add new ones, change their order, and track their performance—all without deploying a new version of your app.

Our [Standard Blinks Library (SBL)](/standard-blinks-library) is the fastest way to discover all available blinks. From swapping and lending to staking and more, all blinks can be found there. They can be customized and integrated into your app with no-code solutions in just a few clicks.

### Multi-Chain Blinks

The blink technology is chain-agnostic. While it originated on Solana, blinks are now fully EVM-compatible. All you need to do is set the correct CORS headers.

```typescript theme={null}
// CORS headers example for multiple chains

import { ACTIONS_CORS_HEADERS } from "@solana/actions";

// CORS for Solana Devnet
const solanaDevnetHeaders = {
  ...ACTIONS_CORS_HEADERS,
  "x-blockchain-ids": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", // CAIP2 SOL devnet
  "x-action-version": "2.4",
};

// CORS for Monad Testnet
const monadHeaders = {
  ...ACTIONS_CORS_HEADERS,
  "x-blockchain-ids": "eip155:10143", // CAIP2 MON testnet
  "x-action-version": "2.4",
};
```

If you want to learn how to build a blink, have a look at our [Guides](/blinks/blinks-provider/guides) or Blinks Provider section.


# Blinks
Source: https://docs.dialect.to/blinks/blinks-client/integrate/ui-components/blinks

A complete, interactive data structure that includes all necessary information to display and interact with a Blink.

A `Blink` contains the complete, interactive data structure. It includes all necessary information to display and interact with a `Blink`, including its current state, possible actions, and related data.

## Web

This section covers adding Blinks directly to your React dApp using our [Blinks React SDK](https://www.npmjs.com/package/@dialectlabs/blinks). The SDK is open-source and can be found on our [Github](https://github.com/dialectlabs/blinks).

<img alt="Blinks component rendered on desktop" />

### Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @dialectlabs/blinks
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @dialectlabs/blinks
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @dialectlabs/blinks
    ```
  </Tab>
</Tabs>

### Adding Component

To simplify the integration, the following hooks are exported from `@dialectlabs/blinks/react`

* `useBlink` - This is the overall hook, it fetches the `BlinkInstance`, initializes a security registry, and refreshes it every 10 minutes.
* `useBlinksRegistryInterval` - This fetches the security registry and refreshes it.
* `useBlinkSolanaWalletAdapter` - This sets up an adapter for `Blink` using a wallet provider.

If you want to build your own hooks, use `Blink` , `BlinksRegistry` , and `BlinkConfig/BlinkAdapter` classes and interfaces.

<Warning>
  If you are using the `useBlinkSolanaWalletAdapter` hook, then be sure to have`<WalletProvider />`and`<WalletModalProvider />` above in the component tree.
</Warning>

### Usage

Here's a basic setup:

```javascript theme={null}
/**
 * Important: This component must be wrapped with <WalletProvider />
 * and <WalletModalProvider /> in your application.
 */

import "@dialectlabs/blinks/index.css";

import {
  Blink,
  useBlink,
  useBlinksRegistryInterval,
} from "@dialectlabs/blinks";
import { useBlinkSolanaWalletAdapter } from "@dialectlabs/blinks/hooks/solana";

const App = () => {
  // URL of your endpoint (blink provider)
  const blinkApiUrl = "...";

  // Initiates adapter
  const { adapter } = useBlinkSolanaWalletAdapter(
    "<YOUR_RPC_URL_OR_CONNECTION>"
  );

  // Fetches the blink from the provided URL
  const { blink, isLoading } = useBlink({ url: blinkApiUrl });

  if (isLoading) return null;

  return <Blink blink={blink} adapter={adapter} />;
};
```

<Tip>
  The URLs in `blinkApiUrl` must be direct Blink provider URLs and not interstitials or website urls with actions.json
</Tip>

## Mobile

This section covers adding blinks directly to your React Native dApp through our [React Native SDK](https://www.npmjs.com/package/@dialectlabs/blinks-react-native) for Blinks. The SDK is completely open-source and can be found on our [GitHub](https://github.com/dialectlabs/blinks-react-native).

<img alt="Blinks component on mobile device" />

### Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @dialectlabs/blinks @dialectlabs/blinks-react-native
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @dialectlabs/blinks @dialectlabs/blinks-react-native
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @dialectlabs/blinks @dialectlabs/blinks-react-native
    ```
  </Tab>
</Tabs>

### Adding Component

The following imports are needed to simplify the Blink integration:

* `useBlink` hook and `BlinkAdapter` type from `@dialectlabs/blinks`
* `Blink` component from `@dialectlabs/blinks-react-native`

### Usage

A `getWalletAdapter` function has to be defined to generate an `BlinkAdapter` for interactions with user wallets, like wallet connect and signing transactions through the React Native dApp.

After that, the `<Blink />` component can be used in the React Native dApp to render the Blink. It takes the following props:

* `theme` - has the styling for the blink to be rendered;
* `blink` - object returned from `useBlink` function (which requires the adapter from `getWalletAdapter` and Blink Provider URL);
* `websiteUrl` - the complete URL of the Blink;
* `websiteText` - the domain name of the Blink URL;

```typescript theme={null}
import { useBlink, type BlinkAdapter } from "@dialectlabs/blinks";
import { Blink } from "@dialectlabs/blinks-react-native";
import { PublicKey } from "@solana/web3.js";
import type React from "react";

function getWalletAdapter(): BlinkAdapter {
  return {
    connect: async (_context) => {
      console.log("connect");
      return PublicKey.default.toString();
    },
    signTransaction: async (_tx, _context) => {
      console.log("signTransaction");
      return {
        signature: "signature",
      };
    },
    confirmTransaction: async (_signature, _context) => {
      console.log("confirmTransaction");
    },
  };
}

export const BlinkInTheWalletIntegrationExample: React.FC<{
  url: string; // could be blink api or website url
}> = ({ url }) => {
  const adapter = getWalletAdapter();
  const { blink } = useBlink({ url });

  if (!blink) {
    // return placeholder component
  }
  const blinkUrl = new URL(url);
  return (
    <Blink
      theme={{
        "--blink-button": "#1D9BF0",
        "--blink-border-radius-rounded-button": 9999,
        // and any other custom styles
      }}
      blink={blink}
      adapter={adapter}
      websiteUrl={blinkUrl.href}
      websiteText={blinkUrl.hostname}
    />
  );
};
```


# MiniBlinks
Source: https://docs.dialect.to/blinks/blinks-client/integrate/ui-components/miniblinks

A way to integrate smaller portions of the full blink into your product. Let you teleport buttons and other single actions between web3 products.

## Overview

Miniblinks are a way to integrate smaller portions of the full blink into your product. In other words, they let you teleport buttons and other single actions between web3 products.

This section describes how to add Miniblinks directly to your web dapp using our Blinks React SDK, or into your mobile dapp using our React Native SDK (coming soon). The SDK is open-source and can be found on our [Github](https://github.com/dialectlabs/blinks).

You can find an example using Miniblinks [here](https://github.com/dialectlabs/blinks/blob/main/examples/mini-blinks/src/App.tsx).

## Concept

Full blinks often contain more than one button or atomic unit of action. In the Donation blink below, there are 4 individual, independent actions:

<img alt="Example of a full blink with multiple donation actions" />

1. Donate 1 SOL
2. Donate 5 SOL
3. Donate 10 SOL
4. Donate a custom amount of SOL.

Because each of these are actions that can be taken individually, they are usable as Miniblinks. For example, you can integrate just the "Donate 1 SOL" Button, or just the input field and button to donate a custom amount of SOL.

## Usage

In this example we'll use the Miniblink SDK component to select just the action corresponding to the custom input field, and render just that.

As usual, we use `useBlink` to fetch the full blink data from an blink URL. The blink object then has all 4 of the possible actions in the `links.actions` attribute.

```typescript theme={null}
const { blink, isLoading } = useBlink({
  url: "solana-action:https://dial.to/api/donate",
});
```

With the above blink, the client will fetch the following JSON:

```json theme={null}
{
  "icon": "https://ucarecdn.com/7aa46c85-08a4-4bc7-9376-88ec48bb1f43/-/preview/880x864/-/quality/smart/-/format/auto/",
  "label": "1 SOL",
  "title": "Donate to Alice",
  "description": "Cybersecurity Enthusiast | Support my research with a donation.",
  "links": {
    "actions": [
      {
        "label": "1 SOL",
        "href": "/api/donate/1"
      },
      {
        "label": "5 SOL",
        "href": "/api/donate/5"
      },
      {
        "label": "10 SOL",
        "href": "/api/donate/10"
      },
      {
        "href": "/api/donate/{amount}",
        "label": "Donate",
        "parameters": [
          {
            "name": "amount",
            "label": "Enter a custom SOL amount"
          }
        ]
      }
    ]
  }
}
```

Miniblinks let us select for just one of the sub actions above using the `selector` attribute, from which we can apply any logic. In this case we use `.find` to select the sub action whose label has "Donate" in the button label, which corresponds to the input field action.

```typescript theme={null}
<Miniblink
  selector={(currentAction) =>
    currentAction.actions.find((a) => a.label === "Donate")!
  }
  blink={blink}
  adapter={adapter}
/>
```

You can do any kind of logic in the `selector` to identify which sub action you want to extract, including using labels, names, existence of `parameters`, or any other data.


# Customize Blink Styles
Source: https://docs.dialect.to/blinks/blinks-client/integrate/ui-components/styling

Dialect's Blinks SDK supports customizable styles so you can render Blinks that match the style of your dApp or 3rd party site.

<img alt="Blinks component with dark theme styling" />

<img alt="Blinks component with light theme styling" />

To render a Blink with a preset, pass `stylePreset` prop (which defaults to `default`, the `dial.to` theme) to `<Blink />` component:

```javascript theme={null}
import { Blink } from '@dialectlabs/blinks';
...
return <Blink stylePreset="x-dark" ... />;
```

## Style Presets

Style presets are mapped to classes in the following way:

* `x-dark` -> `.x-dark`
* `x-light` -> `.x-light`
* `default` -> `.dial-light`
* `custom` -> `.custom`

## CSS Variables

To override a certain preset use the following CSS variables:

```css theme={null}
/*
    Use .x-dark, .x-light, .dial-light, or .custom classes
    .custom - does not contain any colors, radii or shadow
*/
.blink.x-dark {
  --blink-bg-primary: #202327;
  --blink-button: #1d9bf0;
  --blink-button-disabled: #2f3336;
  --blink-button-hover: #3087da;
  --blink-button-success: #00ae661a;
  --blink-icon-error: #ff6565;
  --blink-icon-error-hover: #ff7a7a;
  --blink-icon-primary: #6e767d;
  --blink-icon-primary-hover: #949ca4;
  --blink-icon-warning: #ffb545;
  --blink-icon-warning-hover: #ffc875;
  --blink-input-bg: #202327;
  --blink-input-stroke: #3d4144;
  --blink-input-stroke-disabled: #2f3336;
  --blink-input-stroke-error: #ff6565;
  --blink-input-stroke-hover: #6e767d;
  --blink-input-stroke-selected: #1d9bf0;
  --blink-stroke-error: #ff6565;
  --blink-stroke-primary: #1d9bf0;
  --blink-stroke-secondary: #3d4144;
  --blink-stroke-warning: #ffb545;
  --blink-text-brand: #35aeff;
  --blink-text-button: #ffffff;
  --blink-text-button-disabled: #768088;
  --blink-text-button-success: #12dc88;
  --blink-text-error: #ff6565;
  --blink-text-error-hover: #ff7a7a;
  --blink-text-input: #ffffff;
  --blink-text-input-disabled: #566470;
  --blink-text-input-placeholder: #6e767d;
  --blink-text-link: #6e767d;
  --blink-text-link-hover: #949ca4;
  --blink-text-primary: #ffffff;
  --blink-text-secondary: #949ca4;
  --blink-text-success: #12dc88;
  --blink-text-warning: #ffb545;
  --blink-text-warning-hover: #ffc875;
  --blink-transparent-error: #aa00001a;
  --blink-transparent-grey: #6e767d1a;
  --blink-transparent-warning: #a966001a;

  --blink-border-radius-rounded-lg: 0.25rem;
  --blink-border-radius-rounded-xl: 0.5rem;
  --blink-border-radius-rounded-2xl: 1.125rem;
  --blink-border-radius-rounded-button: 624.9375rem;
  --blink-border-radius-rounded-input: 624.9375rem;

  /* box-shadow */
  --blink-shadow-container: 0px 2px 8px 0px rgba(59, 176, 255, 0.22), 0px 1px
      48px 0px rgba(29, 155, 240, 0.24);
}
```

<Tip>
  Be sure to override with [CSS specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) in mind or by import order.
</Tip>

Using these CSS classes, you can customize the styles to fit the UI of your application.

<img alt="Comparison of different Blinks theme styles" />


# Action Chaining (Multi Step Blinks)
Source: https://docs.dialect.to/blinks/blinks-provider/advanced/action-chaining

Create multi-step experiences with blinks using action chaining

In this section we cover how to use Action Chaining to create multi-step experiences with blinks. Our github has multiple action chaining examples, including

1. [Swapping back and forth between tokens](https://github.com/dialectlabs/actions/blob/main/examples/hono/examples/chaining/post/route.ts)
2. [Inline chaining](https://github.com/dialectlabs/actions/blob/main/examples/hono/examples/chaining/inline/route.ts)
3. [Action chaining with no transaction](https://github.com/dialectlabs/actions/blob/main/examples/hono/examples/chaining/minimal-post/route.ts)
4. [External links](https://github.com/dialectlabs/actions/blob/main/examples/hono/examples/external-link/route.ts)

In this section we walk through the first example, swapping back and forth between tokens. For the remainder, visit the github links above to read the source.

## Example: Swapping back and forth between tokens

<img alt="Action chaining example showing swap flow" />

In [this example](https://github.com/dialectlabs/actions/blob/main/examples/hono/examples/chaining/post/route.ts) we create a blink that swaps from SOL to BONK in the first step, and then from BONK back to SOL in the second.

The first action, `app.get('SOL-BONK', async (c) => { ... }` ([link](https://github.com/dialectlabs/actions/blob/825a1d5a666c05bbd0315c34e3c7481ae6d5a9e3/examples/hono/examples/chaining/post/route.ts#L30)) returns an an input field (a linked parameterized action) for the user to specify the amount to swap. This is no different than a non-chained actions response.

On submit, a POST call is made to `app.post('SOL-BONK/:amount', async (c) => { ... }` ([link](https://github.com/dialectlabs/actions/blob/825a1d5a666c05bbd0315c34e3c7481ae6d5a9e3/examples/hono/examples/chaining/post/route.ts#L74)). This response includes both the transaction data as expected, but now also the `links` attribute with a `next` attribute in it. This `next` attribute powers action chaining.

```typescript theme={null}
const response: ActionPostResponse = {
  transaction: swapResponse.swapTransaction,
  links: {
    next: {
      type: "post",
      href: `/api/chaining/post/swap/BONK-SOL`,
    },
  },
};
```

The `response.links.next.href` URL is the relative path to the next action, and `type: 'post'` indicating that chaining is done through a POST request to the specified href. The alternative chaining method, `type: 'inline'`, will be explained in the next section.

<Tip>
  **✋ Subsequent actions are served via POST, not GET ✋**

  With chained actions, all actions after the first action are retrieved via POST calls rather than GET calls. This is because many subsequent actions may pass the results of the first action, such as the transaction signature or other personalized data, to the server to inform the conditions for the next action. This will help with ensuring no personal data is sent insecurely, and help prevent caching that would return incorrect effects.

  As a result, if you are designing a set of chained actions whose order may be flexible, you will need to write a GET method for the action when it is used at the beginning of the chain, and a POST for all subsequent use.
</Tip>

Once the user signs and the transaction succeeds, the client directs the blink to the next action in the chain, in this case `app.post(/BONK-SOL', async (c) => { ... }` ([link](https://github.com/dialectlabs/actions/blob/825a1d5a666c05bbd0315c34e3c7481ae6d5a9e3/examples/hono/examples/chaining/post/route.ts#L136)), which returns metadata to render the second action in the chain.

```typescript theme={null}
const response: Action = {
  icon: LOGO,
  label: `Buy ${outputToken}`,
  title: `Buy ${outputToken}`,
  description: `Buy ${outputToken} with ${inputToken}. Choose a USD amount of ${inputToken} from the options below, or enter a custom amount.`,
  links: {
    actions: [
      {
        type: "transaction",
        href: `/api/chaining/post/swap/BONK-SOL/{${amountParameterName}}`,
        label: `Buy ${outputToken} (chain)`,
        parameters: [
          {
            name: amountParameterName,
            label: "Enter a custom USD amount",
          },
        ],
      },
    ],
  },
};
```

The remainder of the user journey here has no chaining-specific logic. The user may set the amount they wish to swap and submit, which makes a call to `app.post('/BONK-SOL/:amount', async (c) => { ... }` ([link](https://github.com/dialectlabs/actions/blob/825a1d5a666c05bbd0315c34e3c7481ae6d5a9e3/examples/hono/examples/chaining/post/route.ts#L166)) which then returns the transaction to sign and submit to the blockchain.

See the full code here, or browse other action chaining examples here.

## Inline chaining

When using inline chaining, instead of returning a `links.next.href` string for the URL to call in the next step that would return an Action object, that Action object is returned directly in `links.next.action`.

```typescript theme={null}
const response: ActionPostResponse = {
  transaction: swapResponse.swapTransaction,
  links: {
    next: {
      type: 'inline',
      action: {
        type: 'action',
        icon: '...',
        label: '...',
        ...
      },
    },
  },
};
```

This saves a network call and can help transition the client to then next step in the chain optimistically.

See the full inline chaining example [here](https://github.com/dialectlabs/actions/blob/main/examples/hono/examples/chaining/inline/route.ts).


# Error Handling
Source: https://docs.dialect.to/blinks/blinks-provider/advanced/error-handling

Learn how to implement proper error handling in Blinks to provide users with clear feedback and prevent failed transactions.

<img alt="Example of error message displayed in Blink UI" />

Proper error handling is crucial for Blinks as it provides users with clear feedback when something goes wrong. When an error occurs, the `ActionError` object displays the error message directly in the Blink UI, preventing failed transactions and improving user experience.

## Key Concepts

* **ActionError Object**: Wrap error messages in `ActionError` to display them in the Blink UI
* **Input Validation**: Always validate user inputs before processing transactions
* **User-Friendly Messages**: Provide clear, actionable error messages that help users understand what went wrong
* **HTTP Status Codes**: Use appropriate status codes (400 for validation errors, 500 for server errors)

## Best Practices

<CardGroup>
  <Card title="Input Validation" icon="shield-check">
    Validate all inputs before expensive operations
  </Card>

  <Card title="User-Friendly Messages" icon="message">
    Use specific error messages that guide users to the solution
  </Card>

  <Card title="Graceful Error Handling" icon="handshake">
    Always catch and handle errors gracefully
  </Card>

  <Card title="Server-Side Logging" icon="terminal">
    Log errors server-side for debugging while showing user-friendly messages in the UI
  </Card>
</CardGroup>

## Error Handling Example

Here's how to implement input validation and error handling in our [donation Blink](/blinks/blinks-provider/build-your-first-blink) example:

```typescript theme={null}
import {
  ActionPostRequest,
  ActionPostResponse,
  ActionError,
  ACTIONS_CORS_HEADERS,
} from "@solana/actions";
import { PublicKey } from "@solana/web3.js";

// Other code, such as headers, GET and OPTIONS request, etc. 

export const POST = async (req: Request) => {
  try {
    const url = new URL(req.url);
    const amount = Number(url.searchParams.get("amount"));
    
    // Validate donation amount
    if (!amount || isNaN(amount)) {
      throw new Error("Please enter a valid donation amount");
    }
    
    if (amount < 0.05) {
      throw new Error("Minimum donation is 0.05 SOL");
    }
    
    if (amount > 10) {
      throw new Error("Maximum donation is 10 SOL per transaction");
    }
    
    const request: ActionPostRequest = await req.json();
    
    // Nested validation example: Validate wallet address
    let payer: PublicKey;
    try {
      payer = new PublicKey(request.account);
    } catch {
      throw new Error("Invalid wallet address format");
    }
    
    // Process transaction (simplified for example)
    const transaction = await prepareTransaction(
      connection,
      payer,
      receiver,
      amount
    );
    
    const response: ActionPostResponse = {
      type: "transaction",
      transaction: Buffer.from(transaction.serialize()).toString("base64"),
    };
    
    return Response.json(response, {
      status: 200,
      headers
    });
    
  } catch (error) {
    console.error("Donation error:", error);
    
    // Return ActionError for Blink UI display
    const errorResponse: ActionError = {
      message: error instanceof Error ? error.message : "Internal server error"
    };
    
    return new Response(JSON.stringify(errorResponse), {
      status: 500,
      headers
    });
  }
};

// prepareTransaction function ... 

```


# Forms
Source: https://docs.dialect.to/blinks/blinks-provider/advanced/forms

Build blinks with multiple inputs and advanced input types, similar to HTML forms with validation.

Forms allow you to build blinks with multiple inputs and advanced input types. They work similar to `HTML` forms, meaning you define input types, such as dropdowns, radio buttons, text, etc. and decide which input is required.

<img alt="Examples of blink forms" />

Once the users have finished their inputs, they click on the submit button to send the data to your blinks provider.

Best part: Our blink components even check if the inputs were correct before sending them to your backend, so that you don't have to implement these checks again.

The following examples will show code examples for building forms. We will focus only on the `GET` part. They won't show how `POST` requests look like, because the `POST` interactions work the same way any other blink would. If yo want to see the `POST` part, it is recommended to go to our donation blink example.

<Info>
  Forms usually have multiple input fields. This means that you have to work with `linked actions` meaning you set your input params in the links object (see code example below).
</Info>

## Transfer blink example

This example contains the code for the `GET` request of a SOL transfer blink. As you can see, the blink has two input fields.

<img alt="Transfer SOL blink input fields" />

The first is a text input for the wallet address and the required tag ensures that no empty textfield can be submitted. Second input is a number ensuring that the SOL amount that should be transferred is a number.

```typescript theme={null}
// GET request for SOL transfer blink

export const GET = async (req: Request) => {
  const response: ActionGetResponse = {
    type: "action",
    icon: `${new URL("/transfer-sol.png", req.url).toString()}`,
    label: "Send SOL",
    title: "Send SOL with a Blink",
    description:
      "This Blink demonstrates how to send SOL on the Solana blockchain. It is a part of the official Blink Starter Guides by Dialect Labs.  \n\nLearn how to build this Blink: https://docs.dialect.to/blinks/blinks-provider/build-your-first-blink",
    // If you have multiple inputs
    links: {
      actions: [
        {
          type: "transaction", // Defines this as a blockchain transaction
          label: "Send SOL",
          // This is the endpoint for the POST request
          href: "/api/transfer-sol?receiver={receiver}&amount={amount}",
          // Required user inputs
          parameters: [
            {
              type: "text",
              label: "Recipient Public Key",
              name: "receiver",
              required: true, // Sets input as required
            },
            {
              type: "number", // Input is number, checks this in frontend
              label: "Amount",
              name: "amount",
              required: true, // Sets input as required
            },
          ],
        },
      ],
    },
  };

  // Return the response with proper headers
  return new Response(JSON.stringify(response), {
    status: 200,
    headers,
  });
};
```

## Advanced input types

The example above shows a very basic blink that transfers SOL to another Solana address. As already discussed in this section, there are more input types than text and numbers, which we refer to as advanced input types.

The following advanced input types are available:

* `text`
* `email`
* `URL`
* `numbers`
* `dates`
* `date-times`
* `checkboxes`
* `radio buttons`
* `text areas`
* `select`

## Advanced input examples

Below are more examples that showcase how you can use advanced input types in your code. For full blink examples make sure you visit our [guides section](/blinks/blinks-provider/guides).

### Dropdown and radio buttons

```typescript theme={null}
const payload: ActionGetResponse = {
  title: "Alice's Adventures",
  icon: "<image-url>",
  label: "Donate SOL",
  description: "Cybersecurity Enthusiast | Sign up for my newsletter!",
  links: {
    actions: [
      {
        label: "Sign Up", // button text
        href: "/api/donate?amount={amount}&choice={choice}",
        parameters: [
          {
            type: "select",
            name: "amount", // parameter name in the `href` above
            label: "Donation Amount in SOL", // placeholder of the text input
            required: true,
            options: [
              { label: "1", value: "1" },
              { label: "5", value: "5" },
              { label: "10", value: "10" },
            ],
          },
          {
            type: "radio",
            name: "choice", // parameter name in the `href` above
            label: "Do you want to sign up for our newsletter", // placeholder of the text input
            required: true,
            options: [
              { label: "Yes", value: "1" },
              { label: "No", value: "0" },
            ],
          },
        ],
      },
    ],
  },
};
```

Here's what that would look like when unfurled:

<img alt="Blink with dropdown and radio buttons" />


# Metadata API
Source: https://docs.dialect.to/blinks/blinks-provider/advanced/metadata

Share curated information about your dapp, customized to individual users based on their public key

Protocols now have the capability to share curated information about their dapps, customized to individual users based on their public key.

## API Details

The data format includes key-value pairs that can represent various aspects of a protocol's information, such as extended descriptions, APY, or token balances.

```javascript theme={null}
type DataRow = {
  key: string;
  title: string;
  value: string;
  icon?: string;
  url?: string;
};
type BlinkData = {
  rows: DataRow[];
  extendedDescription: string
};
```

## Response Example

```json theme={null}
{
  "rows": [
    { "key": "apy", "title": "apy", "value": "7%" },
    { "key": "tvl", "title": "TVL", "value": "$2.28M" }
  ],
  "extendedDescription": "*Markdown markup*"
}
```

<Note>
  To streamline ecosystem integration, we recommend placing your metadata API at /metadata.
  This standard location allows for efficient discovery and integration of your information within the ecosystem.
</Note>

## Structure your GET

Here's an example of `GET` request based on Jito's stake blink (with the metadata API located at `/stake/metadata`)

```javascript theme={null}
app.get('/stake/metadata', async (c) => {
  const account = c.req.query('account');
  const connection = new Connection(c.env.SOLANA_RPC_URL);

  const metadataRows: MetadataRow[] = [];

  const [projectedApy, jitoSolRate, solBalance, jitoBalance] =
    await Promise.allSettled([
      getProjectedApy(), 
      // 0.083,
      getJitoSolRate(connection),
      account ? getBalance(new PublicKey(account), connection) : null,
      account
        ? getBalance(
            new PublicKey(account),
            connection,
            new PublicKey('J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn'),
          )
        : null,
    ]);
```

With this `GET` request, your metadata API also gets access to the user's public key via `account`. This allows you to customize what data a user will get based on their wallet.

Check out Jito's Metadata [here](https://jito.dial.to/stake/metadata).


# Multiple Transactions (Experimental)
Source: https://docs.dialect.to/blinks/blinks-provider/advanced/multiple-transactions

Handle complex operations that require multiple transactions to be executed sequentially

<Warning>
  **Experimental Feature**: This feature is not part of the official Solana Actions specification and is not supported by Dialect's official Blinks libraries. It's an experimental extension implemented in the [Solana Blinks Library (SBL)](/standard-blinks-library) for specific use cases.
</Warning>

Some complex DeFi operations, such as leveraged positions or multi-step swaps, require multiple transactions. The [Solana Blinks Library (SBL)](/standard-blinks-library) supports this through an experimental `transactions` response type that extends beyond the official specification.

To see an example of how to use this feature, please see the [Kamino Multiply Blink](/api-reference/multiply/multiply-deposit-1).

## When to Use Multiple Transactions

Multiple transactions are typically needed for:

* **Account setup**: Creating accounts before main operations occurs (e.g. creating a user account before opening a leveraged or multiply position)
* **Complex swaps**: Multi-hop swaps that require intermediate steps
* **Cross-program interactions**: Operations spanning multiple DeFi protocols

## Response Format

When your endpoint needs to return multiple transactions, use `type: "transactions"` instead of `type: "transaction"`:

```typescript theme={null}
// NOTE: This is not supported by the official Solana Actions specification or Dialect's official Blinks libraries.

const response = {
  "type": "transactions",
  "transactions": [
    "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQACBE7a3stN5LHJrX44cP1FkIaonITAwMLOb6DAY1dBfcLhVmS1dVK20+Zktnblf0ulFfcj9pKjky78ZFo5k2VXue4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJ3pq+XM5t6yI0YkskERvUAAjCSZvYuU8EYJEmCAAAArgYUdwveXEzDU4/rOH5Xthg38v1tVup0wgOrmDCtPQcBAwQBAAACrAICAAAACQAAAAAAAABfvRsDY82zhmcO+9DjkuLhkgSLyUvpbqLT9q+7vSWDymW/90HnVbKpvcZJjQUnIqF45YqjJ0Jd9ctA2z7GMLenxVN3RhnMgE5AxRKNmiQDuPQxtGmSGrDIprowQg2OmyC7B0LA0FUQsFaJo77w1bOfduoIBtLIeX9pesBVl+r4j8UOAheNKyGtHwxG2SjFhGRC39BByJa8rQnozC6H2uVlllJZtdMVZBoOIyzri702JmWL6eIm+znJMQF9XommtuOrpq6YqvIDZkLMq7sVGfMkORx8/wdKraYvEyULkJ/5mxMdTzIyEUoQwnBT06y6ctfL+aDEXvdJXrphhyYqP+Hw1eFW5PogQwycz39f51Nb1cAnLnvzBMPDwRkVBNtz8JkA",
    "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQAIDU7a3stN5LHJrX44cP1FkIaonITAwMLOb6DAY1dBfcLhR4Os0DR8xX613OmiGRQktIpOvbZhznjopZwNzu7QAK5aGZKRCAwKHlSddxWFAIzGEH4FyLwVVwt7M4L2Np+03Z9Ckd4rpGlIE1qmjAgQCuZo1XRSO7IDjB82txA6c43P256zUYlOIaJqoBoIs6ECqxs3vzobiiO/tmVujNzkqjhsE4l4xxiBGtlREpJSuV8l/qBfqUoFgP8xGIoTXO6ZCoyXJY9OJInxuz0QKRSODYMLWhOZ2v8QhASOe9jb6fhZAwZGb+UhFzL/7K26csOb57yM5bvF9xJrLEObOkAAAADYsBAXY9PlHxJuYVbehd6MYTBZuERo0No/6KKiJRzHAe05OWi9rmXFe//gFMXzgUOk4tcE5m/nJ6A9k8puNL+G8YQlRLmPFt2B56cMg02FhgxYu8jbUsIf4rxM38ovXgMEedVb8jHAbu50xW7OaBUH/bGy3qP0jlECsc2iVrwTjwSyrLESWMzjaCxBi6hy/z35EQJxLxWvEra+abNDWwAICSASjjbbbWoAzztBa0YdG5ntCBcejj/hyUOJ/hWi/l0TCgggNSc4BQU2NhRTus+Dy/7GggQAAAB5AXoBFAA+AAcABQLAxi0ABgYAGwAvLTIBAQYGAAIAMS0yAQEGBgAaACUtMgEBDAwANDckLyMbIgwMODIQh+c0pwc01MF2yQAAAAAAAAwJAAAdNy8xCTktCvsK50wbC59gAQAMCwAAHTQkHhk3CDktCYg/D7rTmKikAAwLAAAdNCYcHzcIOS0JiD8PutOYqKQBDAYkNwwMDCAIAtqK60/JGWYMAjcdCCGEk+SXwEhZDBEAHTc0JC8jJSEbDDIyOBkeCBDY4L8bzJdmr3bJAAAAAAAADAYkNwwMDCAIAtqK60/JGWYMBiY3DAwMIAgC2orrT8kZZgwDNx0kCCGEk+SXwEhZDBAAHTc0JjEoKQIMMjgfHAgkEKGAj/Wrx8IGIw0DAAAAAAAGBgAbAC8tMgEBCyUyEgACFRQbMS8LCy4LKyoPLA4REhUTEA0yMzISFhMYFBcEAQMwKcEgmzNB1pyBBAIAAAAwZAABEQFkAQLDkwQAAAAAAHzKAAAAAAAAMgAADAwANDckLyMbIgwMODIRuXUAy2D1tLp2yQAAAAAAAAUFD426La5P7U2ZI5iKXZ5DR8PMNGlo1ELnW1nSjqdO0g8FETY4EzIDFBAzPVNUpUWv+E/aHZaWBAfJacEiuQJPEaJHJd+l49iSeZkELTAuLwI1CEE1acTnwEZpPlYuf1bb4FBHxg4hOJmdbNvk6trbsOxAA87EyQXKyIcGC1ZktXVSttPmZLZ25X9LpRX3I/aSo5Mu/GRaOZNlV7nuBwcBAAUGAwgA6yGjOx/BhlwqOZHQo5+LEqIS/jRJNg4sO2THkKIRY/kKExkXFhQYCjIMDQYCMDMBBAM="
  ],
  "mode": "sequential",
  "dialectExperimental": {
    "reference": "5oNDL3swdJJF1g9DzJiZ4ynHXgszjAEpUkxVYejchzrY"
  }
}
```

## Required Fields

| Field                 | Type             | Description                                                                |
| --------------------- | ---------------- | -------------------------------------------------------------------------- |
| `type`                | `"transactions"` | Indicates this response contains multiple transactions                     |
| `transactions`        | `string[]`       | Array of base64-encoded serialized transactions                            |
| `mode`                | `"sequential"`   | Execution mode (currently only "sequential" is supported)                  |
| `dialectExperimental` | `object`         | Contiains a reference key to the track transaction (currently deactivated) |

## Sequential Execution

The `mode: "sequential"` field tells the client to execute transactions one after another, waiting for each to be confirmed before proceeding to the next. This ensures proper ordering for dependent operations.

## Example: Multiply Deposit

Here's an example of implementing a multiply deposit endpoint that returns multiple transactions:

```typescript {26-36} title="src/app/api/actions/multiply-deposit/route.ts" theme={null}

import {
  ActionPostRequest,
  ACTIONS_CORS_HEADERS,
  BLOCKCHAIN_IDS,
} from "@solana/actions";
import { Keypair } from "@solana/web3.js";

// ... other code, such as CORS headers, GET request, etc.

export const POST = async (req: Request) => {
  try {
    const request: ActionPostRequest = await req.json();
    const url = new URL(req.url);

    const amount = Number(url.searchParams.get("amount"));
    const leverage = Number(url.searchParams.get("leverage"));
    const account = request.account;

    // Generate multiple transactions for the multiply operation
    const transactions = await generateMultiplyTransactions(
      account,
      amount,
      leverage
    );

    const response = {
      type: "transactions",
      transactions: transactions.map(tx =>
        Buffer.from(tx.serialize()).toString("base64")
      ),
      mode: "sequential",
      dialectExperimental: {
        reference: Keypair.generate().publicKey.toString()
      }
    };

    return Response.json(response, { headers });
  } catch (error) {
    // Error handling
  }
};

// Helper function to generate multiple transactions
async function generateMultiplyTransactions(
  account: string,
  amount: number,
  leverage: number
) => {
  // Implementation that generates:
  // 1. Setup transaction (create accounts if needed, etc.)
  // 2. Deposit transaction (deposit collateral)
  // 3. Borrow transaction (leverage the position)
  // etc.

  return ["tx1", "tx2", "tx3"];
}
```

## Client Handling

Blink clients that receive multiple transactions must handle them sequentially. For implementation details on the client side, see the [client documentation](/blinks/blinks-client/integrate/headless#handling-multiple-transactions-experimental).


# Message Signing
Source: https://docs.dialect.to/blinks/blinks-provider/advanced/sign-message

Implement message signing in Blinks to verify and authenticate users without paying transaction fees.

Message signing allows users to cryptographically prove their identity and provide data without paying transaction fees. This makes it perfect for authentication, feedback collection, surveys, and any scenario where you need verified user input but don't require on-chain storage.

## Key Concepts

<CardGroup>
  <Card title="Authentication" icon="shield-check">
    Users sign messages with their wallet to authenticate themselves
  </Card>

  <Card title="Cryptographic Proof" icon="key">
    Signatures provide cryptographic proof of wallet ownership
  </Card>

  <Card title="Instant Verification" icon="bolt">
    No blockchain confirmation time - instant verification
  </Card>
</CardGroup>

## When to Use Message Signing vs Transactions

| Feature          | Message Signing                   | Blockchain Transaction          |
| ---------------- | --------------------------------- | ------------------------------- |
| **Cost**         | Free                              | Requires SOL for fees           |
| **Speed**        | Instant                           | Requires confirmation (\~400ms) |
| **Storage**      | Off-chain (database)              | On-chain (permanent)            |
| **Use Cases**    | Authentication, feedback, surveys | Payments, NFT minting, DeFi     |
| **Verification** | Cryptographic signature           | Blockchain consensus            |

## Two Approaches to Message Signing

There are two primary approaches to implementing message signing in Blinks:

### 1. Plain Text Signing

Simple message signing with a static string. Best for basic authentication and use-cases where you don't need the enhanced security of the structured approach.

```typescript title="src/app/api/actions/sign-plain/route.ts" theme={null}
import {
  ActionGetResponse,
  ActionPostRequest,
  ActionPostResponse,
  ActionError,
  ACTIONS_CORS_HEADERS,
  BLOCKCHAIN_IDS
} from "@solana/actions";
import { PublicKey } from "@solana/web3.js";
import nacl from "tweetnacl";
import * as bs58 from "bs58";

const blockchain = BLOCKCHAIN_IDS.mainnet;
const headers = {
  ...ACTIONS_CORS_HEADERS,
  'X-Blockchain-Ids': blockchain,
  'X-Action-Version': '2.4'
};

// The message users will sign
const MESSAGE = "Please sign this message to verify your wallet";

export const OPTIONS = async () => new Response(null, { headers });

export const GET = async (req: Request) => {
  const payload: ActionGetResponse = {
    type: "action",
    icon: new URL("/sign-icon.jpg", req.url).toString(),
    title: "Sign Message Demo",
    description: "Sign a message to verify your wallet ownership",
    label: "Sign Message",
    links: {
      actions: [
        {
          type: "message", // Use 'message' type instead of 'transaction'
          href: "/api/actions/sign-plain",
          label: "Sign Message"
        }
      ]
    }
  };

  return new Response(JSON.stringify(payload), { headers });
};

export const POST = async (req: Request) => {
  try {
    const request: ActionPostRequest = await req.json();
    const { account, signature } = request;

    if (!signature) {
      const error: ActionError = {
        message: "Signature is required for verification"
      };
      return new Response(JSON.stringify(error), { 
        status: 400, 
        headers 
      });
    }

    // Verify the signature
    const isValid = verifySignature(MESSAGE, signature, account);

    if (!isValid) {
      const payload: ActionGetResponse = {
        type: "action",
        icon: new URL("/sign-icon.jpg", req.url).toString(),
        title: "❌ Signature Invalid",
        description: `Invalid signature for account: ${account}`,
        label: "Try Again",
        links: { actions: [] }
      };
      return new Response(JSON.stringify(payload), { headers });
    }

    // Success response
    const payload: ActionGetResponse = {
      type: "action",
      icon: new URL("/sign-icon.jpg", req.url).toString(),
      title: "✅ Signature Verified",
      description: `Successfully verified signature for: ${account}`,
      label: "Completed",
      links: { actions: [] }
    };

    return new Response(JSON.stringify(payload), { headers });

  } catch (error) {
    console.error("Signature verification error:", error);
    const errorResponse: ActionError = {
      message: "Failed to verify signature"
    };
    return new Response(JSON.stringify(errorResponse), { 
      status: 500, 
      headers 
    });
  }
};

// Signature verification utility
function verifySignature(message: string, signature: string, account: string): boolean {
  try {
    const messageBytes = new TextEncoder().encode(message);
    const signatureBytes = bs58.decode(signature);
    const publicKeyBytes = new PublicKey(account).toBytes();
    
    return nacl.sign.detached.verify(
      messageBytes,
      signatureBytes,
      publicKeyBytes
    );
  } catch {
    return false;
  }
}
```

### 2. Structured Message Signing (Recommended)

Uses the SIWS (Sign-In With Solana) standard with anti-replay protection and domain binding. Best for production applications requiring enhanced security.

#### Main Endpoint

```typescript title="src/app/api/actions/sign-structured/route.ts" theme={null}
import {
  ActionGetResponse,
  ActionPostRequest,
  ActionPostResponse,
  ActionError,
  ACTIONS_CORS_HEADERS,
  BLOCKCHAIN_IDS,
  SignMessageData,
  SignMessageResponse
} from "@solana/actions";
import { Keypair, PublicKey } from "@solana/web3.js";
import { createSignMessageText } from "@solana/actions";
import nacl from "tweetnacl";
import * as bs58 from "bs58";

const blockchain = BLOCKCHAIN_IDS.mainnet;
const headers = {
  ...ACTIONS_CORS_HEADERS,
  'X-Blockchain-Ids': blockchain,
  'X-Action-Version': '2.4'
};

// Server signing keypair (store securely in production!)
const SERVER_KEYPAIR = nacl.sign.keyPair.fromSecretKey(
  bs58.decode("YOUR_SECRET_KEY_HERE") // Replace with your secret key
);

export const OPTIONS = async () => new Response(null, { headers });

export const GET = async (req: Request) => {
  const payload: ActionGetResponse = {
    type: "action",
    icon: new URL("/sign-icon.jpg", req.url).toString(),
    title: "Secure Message Signing",
    description: "Sign a structured message with enhanced security",
    label: "Sign Secure Message",
    links: {
      actions: [
        {
          type: "message",
          href: "/api/actions/sign-structured",
          label: "Sign Message"
        }
      ]
    }
  };

  return new Response(JSON.stringify(payload), { headers });
};

export const POST = async (req: Request) => {
  try {
    const request: ActionPostRequest = await req.json();
    const { account, signature, state } = request;

    if (!signature) {
      // First request - generate structured message data
      const signMessageData: SignMessageData = {
        address: account,
        domain: new URL(req.url).hostname,
        statement: "Please sign this message to verify your wallet ownership",
        issuedAt: new Date().toISOString(),
        nonce: Keypair.generate().publicKey.toString(), // Anti-replay protection
      };

      // Create standardized message text
      const message = createSignMessageText(signMessageData);
      
      // Server signs the message to prevent tampering
      const serverSignature = bs58.encode(
        nacl.sign.detached(
          new TextEncoder().encode(message),
          SERVER_KEYPAIR.secretKey
        )
      );

      // Store message and server signature in state
      const stateData = {
        message,
        serverSignature
      };

      const response: SignMessageResponse = {
        type: "message",
        data: signMessageData,
        state: JSON.stringify(stateData),
        links: {
          next: {
            type: "post",
            href: "/api/actions/sign-structured/verify"
          }
        }
      };

      return new Response(JSON.stringify(response), { headers });
    }

    // This shouldn't happen in the main endpoint, but handle gracefully
    return new Response(JSON.stringify({
      message: "Use the verify endpoint for signature verification"
    } as ActionError), { status: 400, headers });

  } catch (error) {
    console.error("Sign message error:", error);
    return new Response(JSON.stringify({
      message: "Failed to process sign message request"
    } as ActionError), { status: 500, headers });
  }
};
```

#### Verification Endpoint

```typescript title="src/app/api/actions/sign-structured/verify/route.ts" theme={null}
import {
  ActionGetResponse,
  ActionPostRequest,
  ActionError,
  ACTIONS_CORS_HEADERS,
  BLOCKCHAIN_IDS
} from "@solana/actions";
import { PublicKey } from "@solana/web3.js";
import nacl from "tweetnacl";
import * as bs58 from "bs58";

const blockchain = BLOCKCHAIN_IDS.mainnet;
const headers = {
  ...ACTIONS_CORS_HEADERS,
  'X-Blockchain-Ids': blockchain,
  'X-Action-Version': '2.4'
};

// Same server keypair as above
const SERVER_KEYPAIR = nacl.sign.keyPair.fromSecretKey(
  bs58.decode("YOUR_SECRET_KEY_HERE")
);

export const OPTIONS = async () => new Response(null, { headers });

export const POST = async (req: Request) => {
  try {
    const request: ActionPostRequest = await req.json();
    const { account, signature, state } = request;

    if (!signature || !state) {
      return new Response(JSON.stringify({
        message: "Signature and state are required"
      } as ActionError), { status: 400, headers });
    }

    // Parse state data
    const { message, serverSignature } = JSON.parse(state) as {
      message: string;
      serverSignature: string;
    };

    // Verify server signature (anti-tampering)
    const serverSignatureValid = verifySignature(
      message,
      serverSignature,
      bs58.encode(SERVER_KEYPAIR.publicKey)
    );

    // Verify user signature
    const userSignatureValid = verifySignature(message, signature, account);

    const isValid = serverSignatureValid && userSignatureValid;

    if (!isValid) {
      const payload: ActionGetResponse = {
        type: "action",
        icon: new URL("/sign-icon.jpg", req.url).toString(),
        title: "❌ Signature Verification Failed",
        description: `Invalid signature. Server: ${serverSignatureValid}, User: ${userSignatureValid}`,
        label: "Try Again",
        links: { actions: [] }
      };
      return new Response(JSON.stringify(payload), { headers });
    }

    // Success - you can now save data to database, authenticate user, etc.
    const payload: ActionGetResponse = {
      type: "action",
      icon: new URL("/sign-icon.jpg", req.url).toString(),
      title: "✅ Signature Verified Successfully",
      description: `Message verified for wallet: ${account}`,
      label: "Completed",
      links: { actions: [] }
    };

    return new Response(JSON.stringify(payload), { headers });

  } catch (error) {
    console.error("Verification error:", error);
    return new Response(JSON.stringify({
      message: "Signature verification failed"
    } as ActionError), { status: 500, headers });
  }
};

function verifySignature(message: string, signature: string, account: string): boolean {
  try {
    const messageBytes = new TextEncoder().encode(message);
    const signatureBytes = bs58.decode(signature);
    const publicKeyBytes = new PublicKey(account).toBytes();
    
    return nacl.sign.detached.verify(
      messageBytes,
      signatureBytes,
      publicKeyBytes
    );
  } catch {
    return false;
  }
}
```

This structured approach uses the SIWS (Sign-In With Solana) standard and provides enhanced security through:

* **Domain binding** - Message is tied to your specific domain
* **Anti-replay protection** - Unique nonce prevents message reuse
* **Timestamp validation** - `issuedAt` helps detect stale requests
* **Server signature** - Prevents message tampering

## Security Considerations

<Warning>
  **Production Security Requirements**

  * Store server keypairs securely (use environment variables)
  * Validate all inputs thoroughly
  * Implement rate limiting to prevent spam
  * Use HTTPS in production
  * Consider nonce expiration for time-sensitive operations
  * Log security events for monitoring
</Warning>

## Common Use Cases

Message signing is ideal for:

* **Wallet Based Login/Authentication** - Sign in to dApps and platforms
* **Token Holder Verification** - Prove ownership of specific tokens or NFTs for access
* **Multi-Step Flows** - Combine with [action chaining](/blinks/blinks-provider/advanced/action-chaining)
* **Whitelist Registration** - Sign up for airdrops, presales, or exclusive events
* **DAO Governance** - Off-chain voting and proposal participation
* **Settings Management** - Change notification preferences, update profile settings

## Integration with Action Chaining

Message signing works seamlessly with [action chaining](/blinks/blinks-provider/advanced/action-chaining) for multi-step flows:

```typescript theme={null}
const response: ActionPostResponse = {
  type: "message",
  message: "Thank you for signing!",
  links: {
    next: {
      type: "post", 
      href: "/api/actions/next-step"
    }
  }
};
```

<Tip>
  **For a complete working example**, see our [Feedback Blink guide](/blinks/blinks-provider/guides/feedback-blink) which implements message signing with database storage and action chaining.
</Tip>


# Track Transactions
Source: https://docs.dialect.to/blinks/blinks-provider/advanced/track-tx

Track the conversion of your transactions by adding a reference key to your API

With our SDKs, you have the ability to track the conversion of your transactions by adding a reference key to your API.

## How it works

1. Create a unique reference (e.g. a random `PublicKey`)
2. Add the reference to the instruction
3. Add the reference to the `POST` response

## Code example

For the full blink, checkout our [donation blink](https://github.com/dialectlabs/actions/blob/main/examples/hono/examples/tx-reference/route.ts#L47) example on GitHub.

```typescript {13,16-20,26,30-32} theme={null}
export const POST = async (request: Request) => {
  try {
    const { account } = (await request.json()) as ActionPostRequest;
    const payer = new PublicKey(account);

    const ix = SystemProgram.transfer({
      fromPubkey: payer,
      toPubkey: new PublicKey(DONATION_DESTINATION_WALLET),
      lamports: DONATION_AMOUNT_SOL * LAMPORTS_PER_SOL,
    });

    // Step 1: Generate random PublicKey
    const reference = Keypair.generate().publicKey;

    // Step 2: Add key to transaction
    ix.keys.push({
      pubkey: reference,
      isSigner: false,
      isWritable: false,
    });

    const transaction = await prepareTransaction([ix], payer);

    // Step 3: Add to response using dialectExperimental
    const response: TransactionResponse & {
        dialectExperimental: { reference: string };
    } = {
      type: "transaction",
      transaction: Buffer.from(transaction.serialize()).toString("base64"),
      dialectExperimental: {
        reference: reference.toString(),
      },
    };

    return Response.json(response, { status: 200, headers });
  }
};
```


# Register your Blink
Source: https://docs.dialect.to/blinks/blinks-provider/blink-registry

Blinks are a new way to interact with crypto transactions. They present an array of exciting new opportunities, along with new attack vectors for bad actors.

Blinks are a new way to interact with crypto transactions. They present an array of exciting new opportunities, along with new attack vectors for bad actors. Safety is a high priority for this new technology, and we'll discuss Dialect's approach to security in this section.

With the help of the Solana Foundation and other community members, Dialect maintains a public registry of blockchain links that have been verified as non-malicious as a public good for the Solana ecosystem. As of launch, only Actions that have been registered in the Dialect registry will unfurl in the Twitter feed when posted.

## Why we need a new registry

Wallet Chrome extensions typically rely on the origin URL of the web page from which a transaction is being created to determine whether that transaction is trustworthy. Blinks break this mould, and make it possible, and common, for transactions to come from providers not affiliated with the site.

## Status

<img alt="Blink security status indicators showing trusted, none, and blocked states" />

Wallets and other clients using Dialect's Blink Client SDK use the registry hosted at [https://dial.to/registry](https://dial.to/registry) to check URLs in the client, and then render Blinks as one of:

1. `trusted`—This action has been registered by the developer and accepted by the registration committee.
2. `none`—The action has not been registered.
3. `blocked`—This action has been flagged as malicious by the registration community.

Users should still take precaution when executing actions, `trusted` or otherwise. Even `trusted` actions may cause unintended consequences—the developer may have bugs in their Blink that cause unintended outcomes for users, or their Blinks provider may get compromised by a third party.

## Registration process

<Info>
  Currently registration review is a manual process, however, we are working toward a future automated registration review process.
</Info>

Submit your Blink to the Registry by sending us an email to [hello@dialect.to](hello@dialect.to).

Please complete the following steps to ensure your submission contains accurate information:

* **Step 1 - Your Action Works:** Ensure your Action performs all tasks correctly and reliably. Thoroughly test it to confirm functionality and avoid rejection. You can test your action at dial.to

* **Step 2 - Have a Clear Action Description:** Provide a clear, detailed description to expedite the review process. A well-matched description and functionality help reviewers approve your action quickly.

* **Step 3 - Test your Action Thoroughly:** Thoroughly test your action in various environments. Consistency and reliability can speed up approval.

* **Step 4 - Build Secure Actions:** Adhere to best security practices to ensure your action is approved. Prioritize security to protect users and gain approval swiftly.

* **Step 5 - Provide a Valid Contact:** Provide accurate contact information for smooth follow-ups and verification. Keeping your contacts updated helps prevent delays.

* **Step 6 - Patience:** We are on a mission to change how experiences are shared on the internet, & are thrilled to have you along for the ride

## Testing unregistered blinks

By default, the security settings won't allow the execution of non-trusted blinks. In order to bypass these settings, you should pass the `securityLevel` prop and set it to either `all` or `non-malicious`

```typescript theme={null}
<Blink action={action} securityLevel="all" />
```

## Work with us on the Registry

Dialect believes trust is never something that can be managed by a centralized authority. In the long term, we are working to create a more decentralized, community-driven system for trust. If you're interested in working on this with us, reach out to us at [hello@dialect.to](mailto:hello@dialect.to).

## Rendering Blinks according to Registry status

Wallets that use Dialect's Blinks clients will use this registry under the hood to decide how to render Blinks. They have two options:

1. Render the Blink with the appropriate registry status, neutral for `trusted`, yellow with a warning for unregistered actions with status `none`, and red for `blocked` actions known to be malicious.
2. Don't render blinks of specific registry statuses.

Today, Phantom, Backpack, and all known wallets implementing Blinks clients for sites such as Twitter have chosen to implement option two. This is because the most conservative thing a Blinks client can do is to not render a Blink with a `none` or `blocked` status. Neither Phantom, Backpack, or Dialect are in the business of deciding what links users can share on an independent site such as Twitter.


# Build your first Blink
Source: https://docs.dialect.to/blinks/blinks-provider/build-your-first-blink

Learn how to create a blink that donates SOL to another wallet using NextJS.

<Tip>
  This is the first of may tutorials that we offer. If you are looking for more
  advanced tutorials, checkout our [guides section](/blinks/blinks-provider/guides/index)
</Tip>

The best way to understand how blinks work, is to build one. This guide will show you, how you can create a blink that donates SOL to another wallet.

For convenience, we will use `NextJS` because it combines very nicely the frontend and backend part into one simple project.

It is important to note here, that blinks are chain agnostic, which means that this blink can be re-created for EVM environments with little alignments in the code.

<Note>
  * Level: Beginner - Requirements: Basic understanding of TypeScript and NextJS
</Note>

## How blinks work

Blinks consist of two parts. A backend part, called the `BlinkProvider` and a frontend part that is referred to as the `BlinkClient`. The client is responsible for state handling and rendering the blink on the frontend, while the provider serves the blink via REST API with simple `GET` and `POST` requests.

This guide will focus on the `BlinkProvider`. If you want to learn about integrating our blink SDK for your front end, please visit our [blink client section](/blinks/blinks-client/integrate).

## Prerequisite

* Code Editor of your choice (recommended [Cursor](https://www.cursor.com/) or [Visual Studio Code](https://code.visualstudio.com/)).
* [Node](https://nodejs.org/en/download) 18.x.x or above.
* Basic TypeScript knowledge.
* Devnet SOL (request airdrop from [Solana Faucet](https://faucet.solana.com/) if you haven't any).

## Initial Setup

### Initialize the project

```bash theme={null}
npx create-next-app@latest blink-starter && cd blink-starter
```

**When prompted, configure your project with these settings:**

✓ Ok to proceed? → Yes \
✓ Would you like to use TypeScript? → Yes \
✓ Would you like to use ESLint? → Yes \
✓ Would you like to use Tailwind CSS? → Yes \
✓ Would you like your code inside a `src/` directory? → Yes \
✓ Would you like to use App Router? → Yes \
✓ Would you like to use Turbopack for `next dev`? → No \
✓ Would you like to customize the import alias (`@/*` by default)? → No

### Install extra packages

Install the packages that you need for this guide.

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @solana/web3.js @solana/actions
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @solana/web3.js @solana/actions
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @solana/web3.js @solana/actions
    ```
  </Tab>
</Tabs>

### Start development server

The development server is used to start a local test environment that runs on your computer. It is perfect to test and develop your blink, before you ship it to production.

```bash theme={null}
npm run dev
```

## Coding time

Now that we have our basic setup finished, it's time to open the editor and start coding.

### Create an endpoint

To write a blink provider, you have to create an endpoint. Thanks to NextJS, this all works pretty straightforward. All you have to do is to create the following folder structure:

```jsx theme={null}
src/
└── app/
    └── api/
        └── actions/
            └── donate-sol/
                └── route.ts
```

### Create actions.json

Finally, you have to create the `actions.json` file which will be hosted in the root directory of your application. This file is needed to tell other applications which blink providers are available on your website. **Think of it as a sitemap for blinks.**

#### File structure

```bash theme={null}
src/
└── app/
    └── actions.json/
        └── route.ts
```

#### Content in file

```tsx theme={null}
// file: src/app/actions.json/route.ts

import { ACTIONS_CORS_HEADERS, ActionsJson } from "@solana/actions";

export const GET = async () => {
  const payload: ActionsJson = {
    rules: [
      // map all root level routes to an action
      {
        pathPattern: "/*",
        apiPath: "/api/actions/*",
      },
      // idempotent rule as the fallback
      {
        pathPattern: "/api/actions/**",
        apiPath: "/api/actions/**",
      },
    ],
  };

  return Response.json(payload, {
    headers: ACTIONS_CORS_HEADERS,
  });
};

// DO NOT FORGET TO INCLUDE THE `OPTIONS` HTTP METHOD
// THIS WILL ENSURE CORS WORKS FOR BLINKS
export const OPTIONS = GET;
```

### Add an image for the blink

Every blink has an image that is rendered on top. If you already have your image hosted somewhere, you can skip this step but if you don't, you can create a `public` folder in your `NextJS` project and copy/paste an image there.

In our example, we will paste a file called `donate-sol.png` into this public folder.

<img alt="Filestructure of project" />

### OPTIONS endpoint and headers

Enable CORS for cross-origin requests and standard headers for the API endpoints. This is the standard configuration for blinks.

```typescript theme={null}
//file: src/app/api/actions/transfer-sol/route.ts

import { ACTIONS_CORS_HEADERS, BLOCKCHAIN_IDS } from "@solana/actions";

// CAIP-2 format for Solana
const blockchain = BLOCKCHAIN_IDS.devnet;

// Set standardized headers for Blink Providers
const headers = {
  ...ACTIONS_CORS_HEADERS,
  "x-blockchain-ids": blockchain,
  "x-action-version": "2.4",
};

// OPTIONS endpoint is required for CORS preflight requests
// Your Blink won't render if you don't add this
export const OPTIONS = async () => {
  return new Response(null, { headers });
};
```

### GET endpoint

`GET` returns the blink metadata and UI configuration.

It describes:

* How the Action appears in Blink clients
* What parameters users need to provide
* How the Action should be executed

```jsx theme={null}
//file: src/app/api/actions/transfer-sol/route.ts

import {
  ActionGetResponse,
  ACTIONS_CORS_HEADERS,
  BLOCKCHAIN_IDS,
} from "@solana/actions";

// GET endpoint returns the Blink metadata (JSON) and UI configuration
export const GET = async (req: Request) => {
  // This JSON is used to render the Blink UI
  const response: ActionGetResponse = {
    type: "action",
    icon: `${new URL("/donate-sol.jpg", req.url).toString()}`,
    label: "1 SOL",
    title: "Donate SOL",
    description:
      "This Blink demonstrates how to donate SOL on the Solana blockchain. It is a part of the official Blink Starter Guides by Dialect Labs.",
    // Links is used if you have multiple actions or if you need more than one params
    links: {
      actions: [
        {
          // Defines this as a blockchain transaction
          type: "transaction",
          label: "0.01 SOL",
          // This is the endpoint for the POST request
          href: `/api/actions/donate-sol?amount=0.01`,
        },
        {
          type: "transaction",
          label: "0.05 SOL",
          href: `/api/actions/donate-sol?amount=0.05`,
        },
        {
          type: "transaction",
          label: "0.1 SOL",
          href: `/api/actions/donate-sol?amount=0.1`,
        },
        {
          // Example for a custom input field
          type: "transaction",
          href: `/api/actions/donate-sol?amount={amount}`,
          label: "Donate",
          parameters: [
            {
              name: "amount",
              label: "Enter a custom SOL amount",
              type: "number",
            },
          ],
        },
      ],
    },
  };

  // Return the response with proper headers
  return new Response(JSON.stringify(response), {
    status: 200,
    headers,
  });
};
```

### Test your Blink

Visit [dial.to](http://dial.to) and type in the link to your blink to see if it works. If your server runs on `localhost:3000` the url should look like this: **`http://localhost:3000/api/actions/donate-sol`**

<img alt="Blink rendered on dial.to" />

### POST endpoint

`POST` creates the transaction in the backend and sends it to the provider. A `POST` request gets sent, once a user clicks on a button.

#### Set donationWallet and add missing imports

Add the imports that are necessary in order to transfer SOL. This part is also used to make small configurations, such as setting the donationWallet address and the `connection`.

The `connection` is later used to send your transaction into the solana network. Because this is an example transfer in the solana devnet, we use their standard endpoint. If you plan to use this blink later in a production environment, you should replace the link with your `RPC` link.&#x20;

```typescript theme={null}
//file: src/app/api/actions/transfer-sol/route.ts

// imports related to the blink
import {
  ActionGetResponse,
  ActionPostRequest,
  ActionPostResponse,
  ACTIONS_CORS_HEADERS,
  BLOCKCHAIN_IDS,
} from "@solana/actions";

// imports for the transaction
import {
  Connection,
  PublicKey,
  LAMPORTS_PER_SOL,
  SystemProgram,
  TransactionMessage,
  VersionedTransaction,
} from "@solana/web3.js";

// Create a connection to the Solana blockchain
const connection = new Connection("https://api.devnet.solana.com");

// Set the donation wallet address
const donationWallet = "YOUR_SOLANA_WALLET_ADDRESS";

// Code from GET, ...
```

#### Create POST request endpoint

This code will be added below our `GET` request in the same file.

```typescript theme={null}
//file: src/app/api/actions/transfer-sol/route.ts

// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {
    // Following code will start here with step 1
  } catch (error) {
    // Log and return an error response
    console.error("Error processing request:", error);
    return new Response(JSON.stringify({ error: "Internal server error" }), {
      status: 500,
      headers,
    });
  }
};
```

#### Extract data from request

The request contains the URL and the account (PublicKey) from the payer.

```tsx theme={null}
//file: src/app/api/actions/transfer-sol/route.ts

// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {
    // Step 1: Extract parameters, prepare data
    const url = new URL(req.url);

    // Amount of SOL to transfer is passed in the URL
    const amount = Number(url.searchParams.get("amount"));

    // Payer public key is passed in the request body
    const request: ActionPostRequest = await req.json();
    const payer = new PublicKey(request.account);

    // Receiver of the donation wallet address
    const receiver = new PublicKey(donationWallet);
  } catch (error) {
    // Error handling
  }
};
```

#### Prepare the transaction

Create a new function that prepares the transaction and add it below the `POST` request.

```tsx theme={null}
//file: src/app/api/actions/transfer-sol/route.ts
const prepareTransaction = async (
  connection: Connection,
  payer: PublicKey,
  receiver: PublicKey,
  amount: number
) => {
  // Create a transfer instruction
  const instruction = SystemProgram.transfer({
    fromPubkey: payer,
    toPubkey: new PublicKey(receiver),
    lamports: amount * LAMPORTS_PER_SOL,
  });

  // Get the latest blockhash
  const { blockhash } = await connection.getLatestBlockhash();

  // Create a transaction message
  const message = new TransactionMessage({
    payerKey: payer,
    recentBlockhash: blockhash,
    instructions: [instruction],
  }).compileToV0Message();

  // Create and return a versioned transaction
  return new VersionedTransaction(message);
};
```

Call `prepareTransaction` in the `POST` request.

```tsx theme={null}
//file: src/app/api/actions/transfer-sol/route.ts

// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {
    // ... previous code from step 1

    const transaction = await prepareTransaction(
      connection,
      payer,
      donationWallet,
      amount
    );
  } catch (error) {
    // Error handling
  }
};
```

#### Finalize

Create `ActionPostResponse` and return it to the client.

```tsx theme={null}
// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {
    // ... previous code from step 1 and 2

    // Create a response with the serialized transaction
    const response: ActionPostResponse = {
      type: "transaction",
      transaction: Buffer.from(transaction.serialize()).toString("base64"),
    };

    // Return the response with proper headers
    return Response.json(response, { status: 200, headers });
  } catch (error) {
    // Error handling
  }
};
```

### Full code

```typescript theme={null}
//file: src/app/api/actions/donate-sol/route.ts

import {
  ActionGetResponse,
  ActionPostRequest,
  ActionPostResponse,
  ACTIONS_CORS_HEADERS,
  BLOCKCHAIN_IDS,
} from "@solana/actions";

import {
  Connection,
  PublicKey,
  LAMPORTS_PER_SOL,
  SystemProgram,
  TransactionMessage,
  VersionedTransaction,
} from "@solana/web3.js";

// CAIP-2 format for Solana
const blockchain = BLOCKCHAIN_IDS.devnet;

// Create a connection to the Solana blockchain
const connection = new Connection("https://api.devnet.solana.com");

// Set the donation wallet address
const donationWallet = "YOUR_SOLANA_WALLET_ADDRESS";

// Create headers with CAIP blockchain ID
const headers = {
  ...ACTIONS_CORS_HEADERS,
  "x-blockchain-ids": blockchain,
  "x-action-version": "2.4",
};

// OPTIONS endpoint is required for CORS preflight requests
// Your Blink won't render if you don't add this
export const OPTIONS = async () => {
  return new Response(null, { headers });
};

// GET endpoint returns the Blink metadata (JSON) and UI configuration
export const GET = async (req: Request) => {
  // This JSON is used to render the Blink UI
  const response: ActionGetResponse = {
    type: "action",
    icon: `${new URL("/donate-sol.jpg", req.url).toString()}`,
    label: "1 SOL",
    title: "Donate SOL",
    description:
      "This Blink demonstrates how to donate SOL on the Solana blockchain. It is a part of the official Blink Starter Guides by Dialect Labs.",
    // Links is used if you have multiple actions or if you need more than one params
    links: {
      actions: [
        {
          // Defines this as a blockchain transaction
          type: "transaction",
          label: "0.01 SOL",
          // This is the endpoint for the POST request
          href: `/api/actions/donate-sol?amount=0.01`,
        },
        {
          type: "transaction",
          label: "0.05 SOL",
          href: `/api/actions/donate-sol?amount=0.05`,
        },
        {
          type: "transaction",
          label: "0.1 SOL",
          href: `/api/actions/donate-sol?amount=0.1`,
        },
        {
          // Example for a custom input field
          type: "transaction",
          href: `/api/actions/donate-sol?amount={amount}`,
          label: "Donate",
          parameters: [
            {
              name: "amount",
              label: "Enter a custom SOL amount",
              type: "number",
            },
          ],
        },
      ],
    },
  };

  // Return the response with proper headers
  return new Response(JSON.stringify(response), {
    status: 200,
    headers,
  });
};

// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {
    // Step 1:Extract parameters from the URL
    const url = new URL(req.url);

    // Amount of SOL to transfer is passed in the URL
    const amount = Number(url.searchParams.get("amount"));

    // Payer public key is passed in the request body
    const request: ActionPostRequest = await req.json();
    const payer = new PublicKey(request.account);

    // Receiver is the donation wallet address
    const receiver = new PublicKey(donationWallet);

    // Step 2: Prepare the transaction
    const transaction = await prepareTransaction(
      connection,
      payer,
      receiver,
      amount
    );

    // Step 3: Create a response with the serialized transaction
    const response: ActionPostResponse = {
      type: "transaction",
      transaction: Buffer.from(transaction.serialize()).toString("base64"),
    };

    // Return the response with proper headers
    return Response.json(response, { status: 200, headers });
  } catch (error) {
    // Log and return an error response
    console.error("Error processing request:", error);
    return new Response(JSON.stringify({ error: "Internal server error" }), {
      status: 500,
      headers,
    });
  }
};

const prepareTransaction = async (
  connection: Connection,
  payer: PublicKey,
  receiver: PublicKey,
  amount: number
) => {
  // Create a transfer instruction
  const instruction = SystemProgram.transfer({
    fromPubkey: payer,
    toPubkey: new PublicKey(receiver),
    lamports: amount * LAMPORTS_PER_SOL,
  });

  // Get the latest blockhash
  const { blockhash } = await connection.getLatestBlockhash();

  // Create a transaction message
  const message = new TransactionMessage({
    payerKey: payer,
    recentBlockhash: blockhash,
    instructions: [instruction],
  }).compileToV0Message();

  // Create and return a versioned transaction
  return new VersionedTransaction(message);
};
```

## Register your blink

Please note that it is strongly advised to [register your blink](/blinks/blinks-provider/blink-registry). Registered blinks will unfurl on social media sites, such as X.

## Conclusion

This guide showed you how to build a blink that sends SOL to another wallet using `NextJS`. The goal was to demonstrate how quickly blinks can be built, and how they work.

At this stage, you could already host your blink making it possible for clients to integrate it into their websites and services.

In the next sections, you will find more use-cases for blinks, including forms, multi-step blinks and much more. You'll learn how to create and customize experiences that fit your users' needs.

If you want more hands-on examples, visit our [guides section](/blinks/blinks-provider/guides/index).


# Fallbacks
Source: https://docs.dialect.to/blinks/blinks-provider/fallbacks

A fallback is your safety net for when a blink fails to load or display as intended.

By hosting a simple website with Dialect's blink client, you guarantee that users can still view and interact with your blink. This step is crucial for maintaining a seamless experience and preventing frustration.

## Scaffolds

<img alt="Screenshot from blink scaffold monad landing page" />

The recommended way to create this fallback website is by using our [scaffolds](/blinks/blinks-starters/index). These are ready-to-go `NextJS` projects, pre-loaded with all the required configurations and dependencies.

With scaffolds, you can skip the tedious setup and jump straight into coding.

## Interstitials

<img alt="Jupiter swap example screenshot from dial.to interstitial" />

Don't want to build from a scaffold? You can use our [dial.to](https://dial.to) website as an interstitial instead. This approach provides the same core functionality (displaying your blink reliably) but with trade-offs: You can't set custom fallback images for social previews, and the URL gets lengthy.

To implement it, prepend the interstitial link to your blink endpoint like this:

```
<INTERSTITIAL_LINK>/?action=solana-action:<LINK_TO_YOUR_BLINK_PROVIDER>
```

For example, here's a Jupiter swap blink from USDC to SOL:

```
https://dial.to/?action=solana-action%3Ahttps%3A%2F%2Fjupiter.dial.to%2Fswap%2FUSDC-SOL
```

Note: Always URL-encode your link after the `solana-action:` parameter to avoid breakage. You can test this by pasting the full URL into a browser to confirm it resolves correctly.

## Comparison

Not sure which approach is right for your project? Use this comparison to help guide your decision:

| Feature                    | Scaffolds                                                                | Interstitials                |
| -------------------------- | ------------------------------------------------------------------------ | ---------------------------- |
| **Setup Required**         | ✅ Minimal setup needed                                                   | ✅ No setup required          |
| **Hosting**                | ⚠️ Requires own hosting ([vercel](https://vercel.com/) for free options) | ✅ No hosting needed          |
| **URL Length**             | ✅ Shorter URLs                                                           | ⚠️ Longer URLs               |
| **Customization**          | ✅ Full control over customization (e.g. fallback images)                 | ⚠️ No custom image control   |
| **Development Experience** | ✅ Tailored development experience                                        | ⚠️ Less branding flexibility |


# Feedback Blink
Source: https://docs.dialect.to/blinks/blinks-provider/guides/feedback-blink

Learn how to build a message signing blink that collects user feedback and saves it to a database

This guide teaches you how to create a feedback collection system using Solana Blinks with **message signing**. Unlike traditional on-chain transactions that cost SOL, message signing is completely free, making it perfect for collecting user feedback, surveys, or any data that doesn't need to be stored on-chain.

<Note>
  **Level:** Intermediate

  **Time Required:** 30-45 minutes

  **GitHub Repository:** [dialectlabs/feedback-blink](https://github.com/dialectlabs/feedback-blink)
</Note>

## Watch the Tutorial

<iframe title="Building a Feedback Blink with Message Signing" />

**[▶️ Watch: Building a Feedback Blink with Message Signing](https://www.youtube.com/watch?v=2FV1JjNjJTQ)** - Follow along as we build this feedback blink from scratch, set up a database, and implement message signing.

## What You'll Learn

In this tutorial, you will:

* Build a **message signing blink** (no transaction fees!)
* Set up a **PostgreSQL database** with Neon
* Use **Prisma ORM** for database operations
* Implement **action chaining** for multi-step flows
* Create **text input parameters** for user feedback
* Handle **CORS** and proper headers for blinks
* Deploy and test your feedback collection system

## Prerequisites

Before starting this tutorial, ensure you have:

* Code Editor of your choice (recommended [Cursor](https://www.cursor.com/) or [Visual Studio Code](https://code.visualstudio.com/))
* [Node.js](https://nodejs.org/en/download) 18.x.x or above installed
* Basic understanding of TypeScript and Next.js
* A [Neon](https://neon.tech/) account for the database (free tier available)
* A Solana wallet for testing (no SOL required - message signing is free!)
* Basic familiarity with REST APIs and databases

## Project Setup

Let's start by creating a new project using the [Dialect Solana Starter](/blinks/blinks-starters/solana) template. This project includes NextJS as well as all the necessary dependencies for building apps on the Solana Blockchain, including the Solana Actions and Blinks SDK.

### Step 1: Initialize the Project

Use the Dialect scaffold to quickly set up a new blink project:

```bash theme={null}
npx create-blinks-app
```

When prompted, configure your project:

```
✓ Select a blockchain: Solana
✓ Project name: feedback-blink
```

Navigate to your project directory:

```bash theme={null}
cd feedback-blink
```

### Step 2: Install Additional Dependencies

We need Prisma for database management:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install prisma @prisma/client
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add prisma @prisma/client
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add prisma @prisma/client
    ```
  </Tab>
</Tabs>

### Step 3: Initialize Prisma

Set up Prisma with PostgreSQL:

```bash theme={null}
npx prisma init
```

This creates:

* `prisma/schema.prisma` - Your database schema file
* `.env` - Environment variables file (add to `.gitignore`!)

### Step 4: Add the Feedback Image

Every blink needs an icon image. Add your feedback image to the public folder:

1. Create or find a feedback-related image (recommended: 1200x630px for optimal display)
2. Save it as `feedback.jpg` in the `public/` folder
3. The image will be available at `/feedback.jpg` in your application

## Database Setup with Neon

Let's set up a PostgreSQL database using Neon's serverless platform.

### Step 1: Create a Neon Database

1. Visit [Neon.tech](https://neon.tech/) and sign up for a free account
2. Click **"Create a project"**
3. Name your project: `feedback-blink`
4. Select your region (choose one close to your users)
5. Click **"Create project"**

### Step 2: Get Your Database Connection String

1. In the Neon dashboard, click **"Connection Details"**
2. Copy the connection string (it looks like: `postgresql://username:password@host/database`)
3. Keep this tab open - you'll need this string in the next step

### Step 3: Configure Environment Variables

Update your `.env` file with the database connection:

```env theme={null}
# Database connection string from Neon
DATABASE_URL="postgresql://username:password@host/database?sslmode=require"

# Optional: Solana RPC endpoint (defaults to mainnet)
NEXT_PUBLIC_SOLANA_RPC_URL="https://api.mainnet-beta.solana.com"
```

<Warning>
  Never commit your `.env` file to version control! Ensure it's in your `.gitignore` file.
</Warning>

### Step 4: Define the Database Schema

Update `prisma/schema.prisma` with our feedback model:

```prisma title="prisma/schema.prisma" theme={null}

generator client {
  provider = "prisma-client-js"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Feedback {
  id        Int      @id @default(autoincrement())
  wallet    String   @db.VarChar(255)
  feedback  String   @db.Text
  createdAt DateTime @default(now())
  
  // Index on wallet for faster queries
  @@index([wallet])
}
```

This schema creates a table with:

* `id` - Auto-incrementing primary key
* `wallet` - The user's Solana wallet address
* `feedback` - The actual feedback text (unlimited length)
* `createdAt` - Timestamp of when feedback was submitted
* Index on `wallet` for efficient queries by user

### Step 5: Create the Database Tables

Push the schema to your Neon database:

```bash theme={null}
npx prisma migrate dev --name init-feedback
```

This command:

1. Creates the SQL migration files
2. Applies the migration to your database
3. Generates the Prisma client

### Step 6: Generate the Prisma Client

Generate the TypeScript client:

```bash theme={null}
npx prisma generate
```

### Step 7: Create the Prisma Client Singleton

Next.js in development mode can create multiple instances of the Prisma client. Create a singleton to prevent this:

```typescript title="src/lib/prisma.ts" theme={null}
import { PrismaClient } from "../generated/prisma";

const globalForPrisma = global as unknown as { prisma: PrismaClient };

export const prisma =
    globalForPrisma.prisma || new PrismaClient();

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;
```

<Note>
  This singleton pattern prevents "too many connections" errors during development with hot reloading.
</Note>

## Building the Feedback Blink

Now let's create the actual blink endpoints.

### Step 1: Create the Folder Structure

Create the following folder structure for your API routes:

```
src/
└── app/
    ├── api/
    │   └── actions/
    │       └── feedback/
    │           ├── route.ts           # Main feedback endpoint
    │           └── complete/
    │               └── route.ts       # Completion endpoint
    └── actions.json/
        └── route.ts                   # Actions discovery file
```

### Step 2: Create the Actions Discovery File

The `actions.json` endpoint tells blink clients what actions are available:

```typescript title="src/app/actions.json/route.ts" theme={null}
import { ACTIONS_CORS_HEADERS, ActionsJson } from "@solana/actions";

export const GET = async () => {
  const payload: ActionsJson = {
    rules: [
      // Map all root level routes to an action
      {
        pathPattern: "/*",
        apiPath: "/api/actions/*",
      },
      // Fallback for nested routes
      {
        pathPattern: "/api/actions/**",
        apiPath: "/api/actions/**",
      },
    ],
  };

  return Response.json(payload, {
    headers: ACTIONS_CORS_HEADERS,
  });
};

// Required for CORS preflight requests
export const OPTIONS = GET;
```

### Step 3: Create the Main Feedback Endpoint

This is where the magic happens. Let's build the main feedback collection endpoint:

```typescript title="src/app/api/actions/feedback/route.ts" theme={null}
import { 
  ActionGetResponse, 
  ActionPostRequest, 
  ActionPostResponse, 
  ACTIONS_CORS_HEADERS, 
  BLOCKCHAIN_IDS 
} from "@solana/actions";
import { prisma } from "@/lib/prisma";

// Use CAIP-2 format for Solana Mainnet
const blockchain = BLOCKCHAIN_IDS.mainnet;

// Headers configuration with blockchain ID and version
const headers = {
  ...ACTIONS_CORS_HEADERS,
  'X-Blockchain-Ids': blockchain,
  'X-Action-Version': '2.4'
};

// OPTIONS handler for CORS preflight requests
export const OPTIONS = async () => {
  return new Response(null, { headers });
}

// GET handler - Returns the blink UI configuration
export const GET = async (req: Request) => {
  const payload: ActionGetResponse = {
    type: 'action',
    title: 'Share Your Feedback',
    description: 'Help us improve Blinks! Tell us what features you need or what could be better.',
    icon: new URL('/feedback.jpg', req.url).toString(),
    label: 'Send Feedback',
    links: {
      actions: [
        {
          // Using 'message' type for message signing (not 'transaction')
          type: 'message',
          href: '/api/actions/feedback?feedback={feedback}',
          label: 'Send Feedback',
          parameters: [
            {
              name: 'feedback',
              type: 'text',  // Use 'text' for single line, 'textarea' for multi-line
              required: true,
              label: "What features are missing or what could be improved?"
            }
          ]
        }
      ]
    }
  };

  return new Response(JSON.stringify(payload), { headers });
};

// POST handler - Processes and stores the feedback
export const POST = async (req: Request) => {
  try {
    // Extract the user's wallet address from the request
    const request: ActionPostRequest = await req.json();
    const { account } = request;

    // Get feedback from URL parameters
    const url = new URL(req.url);
    const feedback = url.searchParams.get("feedback");

    // Validate feedback
    if (!feedback || feedback.trim().length === 0) {
      return new Response(
        JSON.stringify({ error: "Feedback cannot be empty" }), 
        { status: 400, headers }
      );
    }

    // Save feedback to database
    const savedFeedback = await prisma.feedback.create({
      data: {
        wallet: account,
        feedback: feedback.trim()
      }
    });

    console.log(`Feedback saved: ID ${savedFeedback.id} from ${account}`);

    // Return success with chaining to completion step
    const payload: ActionPostResponse = {
      type: "message",
      message: "Thank you for your feedback! 🙏",
      links: {
        next: {
          type: "post",
          href: "/api/actions/feedback/complete"
        }
      }
    }

    return new Response(JSON.stringify(payload), { headers });
    
  } catch (error) {
    console.error("Error saving feedback:", error);
    return new Response(
      JSON.stringify({ error: "Failed to save feedback" }), 
      { status: 500, headers }
    );
  }
};
```

### Step 4: Create the Completion Endpoint

The completion endpoint provides a final confirmation to the user:

```typescript title="src/app/api/actions/feedback/complete/route.ts" theme={null}
import { ACTIONS_CORS_HEADERS, BLOCKCHAIN_IDS, ActionGetResponse } from "@solana/actions";

// Use the same blockchain ID as the main endpoint
const blockchain = BLOCKCHAIN_IDS.mainnet;

const headers = {
  ...ACTIONS_CORS_HEADERS,
  'X-Blockchain-Ids': blockchain,
  'X-Action-Version': '2.4'
};

// OPTIONS handler for CORS
export const OPTIONS = async () => {
  return new Response(null, { headers });
}

// POST handler - Final step in the feedback flow
export const POST = async (req: Request) => {
  const payload: ActionGetResponse = {
    type: "action",
    icon: new URL('/feedback.jpg', req.url).toString(),
    title: "Feedback Received!",
    description: "Your feedback has been successfully recorded. Thank you for helping us improve!",
    label: "Done",
    links: {
      // Empty actions array indicates the flow is complete
      actions: []
    }
  };

  return new Response(JSON.stringify(payload), { headers });
}
```

## Understanding Key Concepts

### Message Signing vs Transactions

This blink uses **message signing** instead of blockchain transactions:

| Feature      | Message Signing          | Transaction           |
| ------------ | ------------------------ | --------------------- |
| **Cost**     | Free                     | Requires SOL for fees |
| **Speed**    | Instant                  | Requires confirmation |
| **Storage**  | Off-chain (database)     | On-chain              |
| **Use Case** | Feedback, authentication | Payments, NFTs        |

<Info>
  **Production-Ready Message Signing**

  This guide demonstrates basic message signing for tutorial purposes. For production applications requiring enhanced security, anti-replay protection, and proper authentication flows, see our [Message Signing documentation](/blinks/blinks-provider/advanced/sign-message) in the advanced section.
</Info>

### Action Chaining

The feedback flow uses action chaining to create a multi-step user experience:

1. **Initial Action** - User enters feedback
2. **Message Signing** - User signs the message with their wallet
3. **Completion** - Final confirmation screen

This is achieved using the `links.next` field in the response:

```typescript theme={null}
links: {
  next: {
    type: "post",
    href: "/api/actions/feedback/complete"
  }
}
```

### CORS Headers

Blinks require specific CORS headers to work across different domains:

* `Access-Control-Allow-Origin: *` - Allows any domain
* `X-Blockchain-Ids` - Identifies supported blockchains
* `X-Action-Version` - Specifies the Actions spec version

## Testing Your Feedback Blink

### Step 1: Start the Development Server

```bash theme={null}
npm run dev
```

Your application will be available at `http://localhost:3000`

### Step 2: Test on the Landing Page

The scaffold includes a built-in Blinks client on the landing page. Update `src/app/page.tsx` to point at your new feedback endpoint. Here are minimal snippets — keep the rest of your page code as-is.

```tsx title="src/app/page.tsx" {5} theme={null}
// ... imports and other code from above

const baseUrl = typeof window !== 'undefined' ? window.location.origin : '';

const blinkApiUrl = `${baseUrl}/api/actions/feedback`;

const { adapter } = useBlinkSolanaWalletAdapter("https://api.mainnet-beta.solana.com");
const { blink, isLoading } = useBlink({ url: blinkApiUrl });

// ... rest of the code
```

Then visit `http://localhost:3000` and interact with the blink directly on the page.

Note: You can still use [dial.to](https://dial.to) as an alternative by pasting `http://localhost:3000/api/actions/feedback`.

### Step 3: Verify Database Entries

Check your database using Prisma Studio:

```bash theme={null}
npx prisma studio
```

This opens a web interface where you can:

* View all feedback entries
* See wallet addresses and timestamps
* Export data if needed

### Step 4: Test Error Handling

Try these scenarios:

* Submit empty feedback (should show error)
* Submit very long feedback (should work)
* Submit multiple times from the same wallet (should all be saved)

## Conclusion

Congratulations! You've built a complete feedback collection system using Solana Blinks with message signing. You've learned how to:

The feedback blink pattern is incredibly versatile. You can adapt it for:

* Customer surveys
* Bug reports
* Contact forms
* User testimonials
* Newsletter signups
* Any data collection that doesn't require on-chain storage

Happy cooking! 🧑‍🍳


# Guides
Source: https://docs.dialect.to/blinks/blinks-provider/guides/index

Practical guides and tutorials for building specific types of Blinks, including real-world examples and implementation patterns.

## Beginner

<CardGroup>
  <Card title="Build Your First Blink" icon="rocket" href="/blinks/blinks-provider/build-your-first-blink">
    Get started with creating your first Blink. This comprehensive guide walks you through the basics of building a functional Blink from scratch.

    **Platform:** Solana
  </Card>

  <Card title="Tip Blink" icon="hand-holding-dollar" href="/blinks/blinks-provider/guides/tip-blink">
    Learn how to create a simple tipping Blink that allows users to send tips to content creators or service providers.

    **Platform:** Monad
  </Card>
</CardGroup>

## Advanced

<CardGroup>
  <Card title="Feedback Blink" icon="comment" href="/blinks/blinks-provider/guides/feedback-blink">
    Learn how to build a Blink that collects feedback from users and stores it in a database using message signing.

    **Platform:** Solana
  </Card>
</CardGroup>

## Contributing

Interested in contributing a guide? We welcome community contributions! Reach out to us at [hello@dialect.to](mailto:hello@dialect.to) to discuss your ideas.


# Tip Blink Monad
Source: https://docs.dialect.to/blinks/blinks-provider/guides/tip-blink

Learn how you can tip $MON to another wallet using the Monad Blockchain and blinks

Purpose of this guide is to teach you how to build a blink from scratch using the `NextJS` framework and `TypeScript`. You will learn the basic project setup and how a blink is structured. At the end, you have a blink that send a tip to a wallet and can be implemented by a blink client.

This guide will not show you how to implement a blink client. If you are looking for a guide, that explains how to integrate an existing blink, checkout our [blink integration guide](/blinks/blinks-client).

<Note>
  Level: Beginner

  Requirements: Basic understanding of TypeScript and NextJS
</Note>

## Prerequisite

* Code Editor of your choice (recommended [Cursor](https://www.cursor.com/) or [Visual Studio Code](https://code.visualstudio.com/)).
* [Node](https://nodejs.org/en/download) 18.x.x or above.
* Basic TypeScript knowledge.
* Testnet MON (Request MON [via form](https://tally.so/r/mRvGyQ) if you haven't any).

## Initial Setup

Start by setting up a new `NextJS` project and add some basic configuration.

### Initialize the project

In your terminal, run the following command.

```bash theme={null}
npx create-next-app@14 blink-starter-monad && cd blink-starter-monad
```

**When prompted, configure your project with these settings:**

```
✓ Ok to proceed? → Yes
✓ Would you like to use TypeScript? → Yes
✓ Would you like to use ESLint? → Yes
✓ Would you like to use Tailwind CSS? → Yes
✓ Would you like your code inside a `src/` directory? → Yes
✓ Would you like to use App Router? → Yes
✓ Would you like to customize the import alias (`@/*` by default)? → No
```

### Install extra packages

Run the following command to install missing dependencies.

```bash theme={null}
npm install @solana/actions wagmi viem@2.x
```

### Start development server

The development server is used to start a local test environment that runs on your computer. It is perfect to test and develop your blink, before you ship it to production.

```bash theme={null}
npm run dev
```

## Coding Time 🚀

Now that we have our basic setup finished, it is time to open the editor and start coding.

### Create an endpoint

To write a blink provider, you have to create an endpoint. Thanks to NextJS, this all works pretty straightforward. All you have to do is to create the following folder structure:

```typescript theme={null}
src/
└── app/
    └── api/
        └── actions/
            └── donate-mon/
                └── route.ts
```

### Create actions.json

Finally, you have to create the `actions.json` file which will be hosted in the root directory of our application. This file is needed to tell other applications which blink providers are available on your website. **Think of it as a sitemap for blinks.**

```typescript theme={null}
// File: src/app/actions.json/route.ts

import { ACTIONS_CORS_HEADERS, ActionsJson } from "@solana/actions";

export const GET = async () => {
  const payload: ActionsJson = {
    rules: [
      // map all root level routes to an action
      {
        pathPattern: "/*",
        apiPath: "/api/actions/*",
      },
      // idempotent rule as the fallback
      {
        pathPattern: "/api/actions/**",
        apiPath: "/api/actions/**",
      },
    ],
  };

  return Response.json(payload, {
    headers: ACTIONS_CORS_HEADERS,
  });
};

// DO NOT FORGET TO INCLUDE THE `OPTIONS` HTTP METHOD
// THIS WILL ENSURE CORS WORKS FOR BLINKS
export const OPTIONS = GET;
```

### Add an image for the blink

Every blink has an image that is rendered on top. If you have your image already hosted somewhere, you can skip this step but if you haven't you can just create a `public` folder in your `NextJS` project and copy/paste an image there.

In our example we will paste a file called `tip-mon.png` into this public folder.

<img alt="Screenshot of public folder in NextJS project" />

### Create environment variables

Our repositories are public and we don't expose any sensitive data such as wallet addresses, RPC data, etc. in there. All this information is kept in `environment` variables.

<Note>
  Depending on the example repository you cloned, there is either a `.env.example` or a `.env`-file. If you find a `.env.example`-file, make sure to rename it to `.env`.

  ```shell theme={null}
  mv .env.example .env
  ```
</Note>

Once that's done, update your `.env` variables, in this case the `NEXT_PUBLIC_RPC_URL`.

```shell theme={null}
// File: .env

# Fill in the URL of your Monad RPC
NEXT_PUBLIC_RPC_URL=<YOUR_RPC_URL>
```

### OPTIONS endpoint, headers and basic config

Enables `CORS` for cross-origin requests and standard headers for the API endpoints. This is standard configuration you do for every blink.

```typescript theme={null}
// File: src/app/api/actions/tip-mon/route.ts

// CAIP-2 format for Monad testnet
const blockchain = "eip155:10143";

// Wallet address that will receive the tips
// here: wevm.eth multichain wallet
const donationWallet = "0xd2135CfB216b74109775236E36d4b433F1DF507B";

// Create headers
const headers = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
  "Access-Control-Allow-Headers":
    "Content-Type, x-blockchain-ids, x-action-version",
  "Access-Control-Expose-Headers": "x-blockchain-ids, x-action-version",
  "Content-Type": "application/json",
  "x-blockchain-ids": blockchain,
  "x-action-version": "2.4",
};

// OPTIONS endpoint is required for CORS preflight requests
// Your Blink won't render if you don't add this
export const OPTIONS = async () => {
  return new Response(null, { headers });
};
```

### GET endpoint

`GET` returns the Blink metadata and UI configuration.

It describes:

* How the Action appears in Blink clients
* What parameters users need to provide
* How the Action should be executed

```typescript theme={null}
// File: src/app/api/actions/tip-mon/route.ts

import { ActionGetResponse } from "@solana/actions";

// ... config code from above (OPTIONS, headers, etc.)

// GET endpoint returns the Blink metadata (JSON) and UI configuration
export const GET = async (req: Request) => {
  // This JSON is used to render the Blink UI
  const response: ActionGetResponse = {
    type: "action",
    icon: `${new URL("/tip-mon.png", req.url).toString()}`,
    label: "1 MON",
    title: "Tip $MON, support Open Source",
    description:
      "Support wevm, creators of wagmi and viem, by tipping them $MON on the Monad Blockchain. Choose recommended amount, or provide a custom amount.",
    // Links is used if you have multiple actions or if you need more than one params
    links: {
      actions: [
        {
          // Defines this as a blockchain transaction
          type: "transaction",
          label: "0.01 MON",
          // This is the endpoint for the POST request
          href: `/api/actions/tip-mon?amount=0.01`,
        },
        {
          type: "transaction",
          label: "0.05 MON",
          href: `/api/actions/tip-mon?amount=0.05`,
        },
        {
          type: "transaction",
          label: "0.1 MON",
          href: `/api/actions/tip-mon?amount=0.1`,
        },
        {
          // Example for a custom input field
          type: "transaction",
          href: `/api/actions/tip-mon?amount={amount}`,
          label: "Donate",
          parameters: [
            {
              name: "amount",
              label: "Enter a custom MON amount",
              type: "number",
            },
          ],
        },
      ],
    },
  };

  // Return the response with proper headers
  return new Response(JSON.stringify(response), {
    status: 200,
    headers,
  });
};
```

### Test your Blink (optional)

<Warning>
  Note: [dial.to](http://dial.to/) currently supports only `GET` previews for
  `EVM`. To test your `POST` endpoint, please follow the tutorial to the end,
  where we implement the blink client in the frontend.
</Warning>

Visit [dial.to](http://dial.to/) and type in the link to your blink to see if it works. If your server runs on `localhost:3000` the url should be like this: `http://localhost:3000/api/actions/tip-mon`

<img alt="Screenshot of a blink rendered on dial.to" />

### POST endpoint

`POST` handles the actual MON transfer transaction.

#### POST request to the endpoint

Create the post request structure and add the necessary imports as well as the `destinationWallet` on top of the file.

```typescript theme={null}
// File: src/app/api/actions/tip-mon/route.ts

// Update your imports
import { ActionGetResponse, ActionPostResponse } from "@solana/actions";
import { serialize } from "wagmi";
import { parseEther } from "viem";

// ... code from above

// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {
    // Following code wil start here with step 1
  } catch (error) {
    // Log and return an error response
    console.error("Error processing request:", error);
    return new Response(JSON.stringify({ error: "Internal server error" }), {
      status: 500,
      headers,
    });
  }
};
```

#### Extract data from request

The request contains the URL, which contains the `amount` param.

```typescript theme={null}
// File: src/app/api/actions/tip-mon/route.ts

// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {
    // Step 1: Extract amount from URL
    const url = new URL(req.url);
    const amount = url.searchParams.get("amount");

    if (!amount) {
      throw new Error("Amount is required");
    }
  } catch (error) {
    // Log and return an error response
    console.error("Error processing request:", error);
    return new Response(JSON.stringify({ error: "Internal server error" }), {
      status: 500,
      headers,
    });
  }
};
```

#### Create the transaction

Create a new transaction with all the necessary data and add it below in the `POST` request.

```typescript theme={null}
// File: src/app/api/actions/tip-mon/route.ts

// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {
    // ... code from step 1

    // Step 2: Build the transaction
    const transaction = {
      to: donationWallet,
      value: parseEther(amount).toString(),
      chainId: "10143",
    };

    const transactionJson = serialize(transaction);
  } catch (error) {
    // Log and return an error response
    console.error("Error processing request:", error);
    return new Response(JSON.stringify({ error: "Internal server error" }), {
      status: 500,
      headers,
    });
  }
};
```

#### Finalize

Create `ActionPostResponse` and return it to the client.

```typescript theme={null}
// File: src/app/api/actions/tip-mon/route.ts

// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {
    // ... code from step 1 + 2

    // Step 3: Build the response ...
    const response: ActionPostResponse = {
      type: "transaction",
      transaction: transactionJson,
      message: "Your tip has been sent!",
    };

    // ... and return to client
    return new Response(JSON.stringify(response), {
      status: 200,
      headers,
    });
  } catch (error) {
    // Log and return an error response
    console.error("Error processing request:", error);
    return new Response(JSON.stringify({ error: "Internal server error" }), {
      status: 500,
      headers,
    });
  }
};
```

### Full code for blink provider (API)

```typescript theme={null}
// File: src/app/api/actions/tip-mon/route.ts

import { ActionGetResponse, ActionPostResponse } from "@solana/actions";
import { serialize } from "wagmi";
import { parseEther } from "viem";

// CAIP-2 format for Monad
const blockchain = "eip155:10143";

// Wallet address that will receive the tips
const donationWallet = "0xd2135CfB216b74109775236E36d4b433F1DF507B"; // wevm.eth multichain wallet

// Create headers with CAIP blockchain ID
const headers = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
  "Access-Control-Allow-Headers":
    "Content-Type, x-blockchain-ids, x-action-version",
  "Access-Control-Expose-Headers": "x-blockchain-ids, x-action-version",
  "Content-Type": "application/json",
  "x-blockchain-ids": blockchain,
  "x-action-version": "2.4",
};

// OPTIONS endpoint is required for CORS preflight requests
// Your Blink won't render if you don't add this
export const OPTIONS = async () => {
  return new Response(null, { headers });
};

// GET endpoint returns the Blink metadata (JSON) and UI configuration
export const GET = async (req: Request) => {
  // This JSON is used to render the Blink UI
  const response: ActionGetResponse = {
    type: "action",
    icon: `${new URL("/tip-mon.png", req.url).toString()}`,
    label: "1 MON",
    title: "Tip $MON, support Open Source",
    description:
      "Support wevm, creators of wagmi and viem, by tipping them $MON on the Monad Blockchain. Choose recommended amount, or provide a custom amount.",
    // Links is used if you have multiple actions or if you need more than one params
    links: {
      actions: [
        {
          // Defines this as a blockchain transaction
          type: "transaction",
          label: "0.01 MON",
          // This is the endpoint for the POST request
          href: `/api/actions/tip-mon?amount=0.01`,
        },
        {
          type: "transaction",
          label: "0.05 MON",
          href: `/api/actions/tip-mon?amount=0.05`,
        },
        {
          type: "transaction",
          label: "0.1 MON",
          href: `/api/actions/tip-mon?amount=0.1`,
        },
        {
          // Example for a custom input field
          type: "transaction",
          href: `/api/actions/tip-mon?amount={amount}`,
          label: "Donate",
          parameters: [
            {
              name: "amount",
              label: "Enter a custom MON amount",
              type: "number",
            },
          ],
        },
      ],
    },
  };

  // Return the response with proper headers
  return new Response(JSON.stringify(response), {
    status: 200,
    headers,
  });
};

// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {
    // Extract amount from URL
    const url = new URL(req.url);
    const amount = url.searchParams.get("amount");

    if (!amount) {
      throw new Error("Amount is required");
    }

    // Build the transaction
    const transaction = {
      to: donationWallet,
      value: parseEther(amount).toString(),
      chainId: "10143",
    };

    const transactionJson = serialize(transaction);

    // Build ActionPostResponse
    const response: ActionPostResponse = {
      type: "transaction",
      transaction: transactionJson,
      message: "Your tip has been sent!",
    };

    // Return the response with proper headers
    return new Response(JSON.stringify(response), {
      status: 200,
      headers,
    });
  } catch (error) {
    // Log and return an error response
    console.error("Error processing request:", error);
    return new Response(JSON.stringify({ error: "Internal server error" }), {
      status: 500,
      headers,
    });
  }
};
```

## Conclusion

In this tutorial, you learned, how to create a simple blink that tips another wallet. The main focus was to get you familiar with the concept of the blink provider. There is more functionalities, that you can add to your blinks, such as multi steps, input fields, and much more.

The next step is to get your blink deployed for use, and then register your blink. By registering your blink, it gets added to our library, giving you extra distribution and exposure. It also ensures that your blink will unfurl and be usable on X.

In the next tutorial, you will learn how you can implement the blink client, that renders your blink in the frontend.


# Introduction
Source: https://docs.dialect.to/blinks/blinks-provider/index

Blinks are distributable experiences that can be embedded anywhere a link can exist. They represent a modern alternative to traditional SDKs, offering a streamlined, maintainable way to expose your services to the world.

As a blink provider, your backend is the engine that powers these experiences, delivering functionality to clients and integrations effortlessly.

The Blinks Provider ecosystem equips you with the tools and infrastructure to create, manage, and serve blinks from your backend, ensuring they're reliable, scalable, and easy to distribute.

## Key Benefits

Think of your blink providers as hosted endpoints, that you provide for devs to easily integrate with your service using nothing but an URL.

* **Rapid Adoption**: Enable other developers to integrate your service in seconds by sharing a simple link, while you retain full control over the blink's behavior.
* **Consistent Delivery**: Guarantee that your service's logic and design principles are enforced across all implementations, no matter where your blink is used.
* **Seamless Updates**: Update your blink's functionality or UI once on your backend, and see changes reflected instantly everywhere it's embedded—no SDK versioning required.

## Concept

Blink Providers are APIs that deliver signable transactions and messages.

Blink Clients determine if URLs conform to the Actions spec and introspect the underlying Blink Provider APIs to construct interfaces for them.

<img alt="Diagram showing JSON response converted to interactive Blink" />

Blinks, or Blockchain Links, are hosted at URLs and are sharable with this URL. They are built from the following components:

1. A URL scheme for identifying Blink Providers. There are three ways this can work--explicitly sharing an Blink URL, sharing a link to a website with a properly-configured `actions.json` file, and embedding an Blink URL in an `interstitial` site.
2. A `GET` route that interacts with the Blink Provider. It can send a `GET` request to the URL and receive a `GET` response in return to present the client with human-readable information.
3. A `POST` route that interacts with the Blink Provider. It can send a `POST` request to the URL and get a response back to construct transactions, sign them, and submit them to the blockchain.

<img alt="Flow diagram of Blinks provider to client interaction" />

## What's Next?

Ready to dive in? Here are three paths to get you started!

<CardGroup>
  <Card title="Beginner" icon="graduation-cap" href="/blinks/blinks-provider/build-your-first-blink">
    Want to get started? Let's build your first blink together! Follow our step-by-step tutorial to see it in action.
  </Card>

  <Card title="Advanced" icon="code" href="/blinks/blinks-provider/guides/index">
    Not your first rodeo or need more complex solutions? Check out our guides section for in-depth examples and best practices.
  </Card>

  <Card title="Freestyler" icon="rocket" href="/blinks/blinks-starters/index">
    Prefer to experiment on your own? Clone our starters and start building right away.
  </Card>
</CardGroup>


# EVM Starter
Source: https://docs.dialect.to/blinks/blinks-starters/evm

The blink starter for EVM is the fastest way to start with your blink project across EVM-compatible chains.

Blink starter EVM acts as a downloadable and reusable template that utilizes `NextJS` and `Tailwind` as the front end framework plus API routes for the backend. It comes with all necessary dependencies and configuration out of the box, so that you can immediately start building across any EVM-compatible network.

<img alt="Screenshot from blink scaffold EVM landing page" />

### Features

* Nextjs React framework
* Tailwind
* Blink SDK
* Solana Actions
* Connectkit
* Wagmi
* Viem

### Supported Chains

Currently supported EVM-compatible chains:

* **Sei**
* **Monad**
* **Sepolia**

Want to add support for additional chains or wallets? Check out our [contribution guidelines](https://github.com/dialectlabs/blink-starter-evm/blob/main/CONTRIBUTING.md) to learn how you can contribute.

### Installation

#### Run our Starter command

To install the starter, all you have to do is run the command below in your terminal.

```bash theme={null}
npx create-blinks-app
```

### Run on localhost

Run the following command in your terminal

```bash theme={null}
npm run dev
```

Open your browser and visit `http://localhost:3000`. Please be reminded that the port 3000 could also be a different port. It is recommended to check the port in your terminal.

### GitHub Repository

Access the complete source code and examples at: [https://github.com/dialectlabs/blink-starter-evm](https://github.com/dialectlabs/blink-starter-evm)


# Overview
Source: https://docs.dialect.to/blinks/blinks-starters/index

Pre-configured templates to help you build Blinks out of the box.

## What Are Starters?

Starters are ready-to-use project templates that handle initial setup and configuration. They come with essential dependencies, tools, and examples so you can focus on building your blockchain experiences.

## Why Use Starters?

Every `Blink` consists of two core components: a `Blinks Provider` (backend) and a `Blinks Client` (frontend). Our starters make working with both seamless:

<CardGroup>
  <Card title="Next.js Foundation" icon="code">
    Built on Next.js for robust provider-client communication
  </Card>

  <Card title="Zero Config" icon="wand-magic-sparkles">
    Pre-wired with wallet connections, blockchain SDKs, and dev tools
  </Card>

  <Card title="Local Testing" icon="flask">
    Ready-made examples to test your full Blink locally
  </Card>

  <Card title="Chain Agnostic" icon="globe">
    Deploy to any blockchain by updating the chainId
  </Card>
</CardGroup>

## Getting Started

To get you started, all you have to do is run the command below in your terminal. This will guide you through a small config process that helps you setup your project with our latest tools, install dependencies etc.

```bash theme={null}
npx create-blinks-app
```

After you've executed the command, just `cd` into your new starter project folder and run:

```bash theme={null}
npm run dev
```

## Available Starters

<Card title="Solana Starter" icon="link" href="/blinks/blinks-starters/solana">
  Ready-to-use template for building Blinks on the Solana blockchain with pre-configured wallet connections and dev tools.
</Card>

<Card title="Monad Starter" icon="cube" href="/blinks/blinks-starters/monad">
  Complete starter template for Monad blockchain development with EVM compatibility and optimized tooling.
</Card>


# Solana Starter
Source: https://docs.dialect.to/blinks/blinks-starters/solana

The blink starter for Solana is the fastest way to start with your blink project.

Blink starter Solana acts as a downloadable and reusable template that utilizes `NextJS` and `Tailwind` as the front end framework plus API routes for the backend. It comes with all necessary dependencies and configuration out of the box, so that you can immediately start building.

<img alt="Screenshot from Dialect's Blink Solana Scaffold" />

### Features

* Nextjs React framework
* Tailwind
* Blink SDK
* Solana Web3.js
* Dark/Light Mode
* Solana Wallet Adapter

### Installation

#### Run our Starter command

To install the starter, all you have to do is run the command below in your terminal.

```bash theme={null}
npx create-blinks-app
```

### Run on localhost

Run the following command in your terminal

```bash theme={null}
npm run dev
```

Open your browser and visit `http://localhost:3000`. Please be reminded that the port 3000 could also be a different port. It is recommended to check the port in your terminal.


# Blinks
Source: https://docs.dialect.to/blinks/index

Blockchain Links that make onchain experiences distributable and actionable everywhere

<Tip>
  **New: Blinks in Alerts**<br />
  Blinks can now be embedded in alerts for actionable notifications with full position context. Users can complete onchain transactions directly in apps without redirects. [Learn more](/alerts/blinks-in-alerts)
</Tip>

Blockchain Links, aka Blinks, are the fastest way to take onchain experiences and make them distributable and actionable everywhere. This technology lets applications unbundle their product experiences from their apps and sites, allowing users to take instant, no-redirect actions wherever they are.

<img alt="Blinks in various environments" />

Any client that has blinks integrated into their application can point to a blockchain link which will automatically unfurl into complete, interactive experiences. Blinks don't just remove the need of SDKs in most cases, but also ensure that the implementation of your service follows your design principles and best practices, reducing the risk of incorrect implementations or poor user experiences.

By building with blinks, you ensure that developers can integrate your service in seconds while you still own the blink. Since you maintain full control of the blink from a single location, any updates you make are automatically reflected wherever your blink is served, eliminating the need for third parties to update their SDKs.

<img alt="Partner ecosystem using Blinks" />

The ecosystem's most innovative teams are already building with Blinks, creating powerful new ways to interact with blockchain technology. This widespread adoption opens up exciting possibilities for both developers and users.

These docs cover the Blinks specification, how Blinks are built, how they unfurl natively in front ends (or via chrome extensions), and provide practical resources on how to get started developing today.


# Welcome to Dialect
Source: https://docs.dialect.to/index

The complete UX stack for Web3 - transforming links into blockchain actions and keeping users engaged with real-time notifications

## Get started

If you're new to Dialect, start here to learn the essentials and start building.

<CardGroup>
  <Card title="Blinks Quickstart" icon="bolt" href="/blinks">
    Create seamless blockchain interactions.
  </Card>

  <Card title="Alerts Quickstart" icon="bell" href="/alerts/quick-start">
    Send notifications in under 15 minutes.
  </Card>

  <Card title="API Guide" icon="code" href="/standard-blinks-library/">
    Build with any tech stack using our APIs.
  </Card>

  <Card title="Request API Keys" icon="key" href="/request-api-keys">
    Get your API keys for Alerts, Blinks, and Markets products.
  </Card>
</CardGroup>

## Blinks

<CardGroup>
  <Card title="Build Blinks" icon="hammer" href="/blinks/blinks-provider">
    Create new blockchain actions and transform URLs into interactive
    experiences.
  </Card>

  <Card title="Integrate Blinks" icon="puzzle-piece" href="/blinks/blinks-client">
    Add Blinks to your application with React components or headless
    integration.
  </Card>

  <Card title="Standard Blinks Library" icon="book" href="/standard-blinks-library">
    Ready-to-use Blinks from top Solana ecosystem projects. Copy, paste, done.
  </Card>
</CardGroup>

## Alerts

<CardGroup>
  <Card title="Real-time Notifications" icon="bell" href="/alerts">
    Build advanced notification systems with multi-channel delivery including
    in-app, email, and push notifications.
  </Card>

  <Card title="Event Detection & Monitoring" icon="chart-bar" href="/alerts/alerts-and-monitoring">
    Monitor blockchain events and integrate alerting for your applications with
    custom triggers.
  </Card>

  <Card title="Universal Inbox" icon="inbox" href="/alerts/integrate-inbox/universal-inbox">
    Add an inbox to your app that receives notifications from multiple
    protocols, so users never miss important updates.
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://dashboard.dialect.to/">
    Send events and manage notifications through our no-code dashboard
    interface.
  </Card>
</CardGroup>

## Markets and Positions

<CardGroup>
  <Card title="Markets and Position Data" icon="building-columns" href="/markets">
    Get real-time lending rates, market data, and position tracking for Solana's
    top lending protocols with ready-to-use Blinks.
  </Card>

  <Card title="Markets API Reference" icon="code" href="/api-reference/markets/list-all-markets">
    Access lending market and position data through our RESTful API.
  </Card>
</CardGroup>


# Request Client Keys
Source: https://docs.dialect.to/markets/api-keys

Get client keys for the Markets and Positions APIs and fetch real-time market data and track open positions from Solana's top DeFi protocols.

<img alt="Request Client Keys for Markets" />

<Note>
  Code examples in this documentation use a `pk_demo` client key. This key is
  heavily rate limited and intended only for the API Playground. Request your
  own key for production use.
</Note>

To request your client keys for the Markets and Positions APIs, please send us an email at [hello@dialect.to](mailto:hello@dialect.to).


# Historical Position Data
Source: https://docs.dialect.to/markets/history

Track position value changes over time with historical snapshots from the Markets and Positions API.

<Check>
  Historical data is available from **October 8, 2025** onwards. Backfilling to earlier dates will be added in a future release.
</Check>

## Overview

Historical data allows you to track how your DeFi positions have changed over time.

<CardGroup>
  <Card title="Portfolio Tracking" icon="wallet">
    See your total portfolio value across all protocols
  </Card>

  <Card title="Performance Analysis" icon="chart-line">
    Understand returns over time
  </Card>

  <Card title="Historical Charts" icon="chart-area">
    Visualize position growth and changes
  </Card>
</CardGroup>

Historical data tracks **cumulative values**, meaning the raw balances in your positions. This includes natural yield accumulation as well as any deposits or withdrawals you make.

## What Data is Available

Historical snapshots are available for **position attributes only**. These attributes enable you to track your portfolio's value over time in both native tokens and in USD.

| Attribute   | Description                                |
| ----------- | ------------------------------------------ |
| `amount`    | Position balance in native token units     |
| `amountUsd` | Position balance in USD equivalent         |
| `timestamp` | When this snapshot was recorded (RFC 3339) |

## Get Historical Snapshots

Fetch position snapshots for any time range:

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Get history from launch date (Oct 8, 2025) to now
  const endDate = new Date().toISOString();
  const startDate = '2025-10-08T00:00:00Z'; // Historical data starts from this date

  const response = await fetch(
    'https://markets.dial.to/api/v0/positions/history?' + new URLSearchParams({
      walletAddress: '6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176',
      startTime: startDate,
      endTime: endDate
    }),
    {
      headers: {
        'x-dialect-client-key': 'YOUR_CLIENT_KEY'
      }
    }
  );

  const data = await response.json();
  ```

  ```bash cURL theme={null}
  # Replace end date with current date
  curl -X GET "https://markets.dial.to/api/v0/positions/history?walletAddress=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176&startTime=2025-10-08T00:00:00Z&endTime=2025-10-10T23:59:59Z" \
    -H "x-dialect-client-key: YOUR_CLIENT_KEY"
  ```
</CodeGroup>

### Query Parameters

| Parameter       | Required | Description                                                                                               |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `walletAddress` | Yes      | Wallet address to fetch position history for                                                              |
| `startTime`     | Yes      | Start of time range (RFC 3339 format, e.g., `2025-10-08T00:00:00Z`)                                       |
| `endTime`       | Yes      | End of time range (RFC 3339 format, e.g., `2025-10-10T23:59:59Z`)                                         |
| `positionIds`   | No       | Optional array of position IDs to filter. If empty, returns all positions                                 |
| `resolution`    | No       | Time interval for data points. Options: `1m`, `5m`, `1h`, `1d`. See [Resolution](#resolution) for details |

### Response Structure

In the example below, you see an example of the response structure, that shows the Lulo Regular position with two snapshots showing growth from 1.02 to 2.02 USDC. Later in this document, you will learn how to [use](/markets/history#practical-examples) and [interpret](/markets/history#understanding-cumulative-values) this data.

```json theme={null}
{
  "data": {
    "positions": [
      {
        "id": "lulo.regular.HwE39BAt5i6ymd8hhZbaxTrYf61ifm8PRwJpm4o9ULzj",
        "providerId": "lulo",
        "type": "yield",
        "marketId": "lulo.regular",
        "history": [
          {
            "timestamp": "2025-10-08T16:24:29.000Z",
            "amount": 1.018845,
            "amountUsd": 1.02
          },
          {
            "timestamp": "2025-10-09T21:16:12.000Z",
            "amount": 2.017082,
            "amountUsd": 2.02
          }
        ]
      }
    ]
  }
}
```

<Accordion title="View Full Response (11 positions)">
  The response above shows 2 positions of the response to facilitate readability. The full response for this wallet contains 11 positions across Lulo, Jupiter, and Kamino. The following examples use the complete dataset.

  ```json theme={null}
  {
    "data": {
      "positions": [
        {
          "id": "lulo.protected.HwE39BAt5i6ymd8hhZbaxTrYf61ifm8PRwJpm4o9ULzj",
          "providerId": "lulo",
          "type": "yield",
          "marketId": "lulo.protected",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 1.012845,
              "amountUsd": 1.01
            },
            {
              "timestamp": "2025-10-09T21:21:20.000Z",
              "amount": 1.999995,
              "amountUsd": 2
            }
          ]
        },
        {
          "id": "lulo.regular.HwE39BAt5i6ymd8hhZbaxTrYf61ifm8PRwJpm4o9ULzj",
          "providerId": "lulo",
          "type": "yield",
          "marketId": "lulo.regular",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 1.018845,
              "amountUsd": 1.02
            },
            {
              "timestamp": "2025-10-09T21:16:12.000Z",
              "amount": 2.017082,
              "amountUsd": 2.02
            }
          ]
        },
        {
          "id": "jupiter.earn.SOL.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
          "providerId": "jupiter",
          "type": "yield",
          "marketId": "jupiter.earn.SOL",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 0.001000981,
              "amountUsd": 0.22
            }
          ]
        },
        {
          "id": "jupiter.borrow.1.2433.deposit",
          "providerId": "jupiter",
          "type": "lending",
          "marketId": "jupiter.borrow.1",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 0.015060546,
              "amountUsd": 3.34
            }
          ]
        },
        {
          "id": "jupiter.borrow.1.2433.borrow",
          "providerId": "jupiter",
          "type": "lending",
          "marketId": "jupiter.borrow.1",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 1.012172,
              "amountUsd": 1.01
            }
          ]
        },
        {
          "id": "jupiter.earn.USDC.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
          "providerId": "jupiter",
          "type": "yield",
          "marketId": "jupiter.earn.USDC",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 0.100776,
              "amountUsd": 0.1
            }
          ]
        },
        {
          "id": "jupiter.borrow.7.1228.deposit",
          "providerId": "jupiter",
          "type": "lending",
          "marketId": "jupiter.borrow.7",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 1.331889,
              "amountUsd": 1.5
            }
          ]
        },
        {
          "id": "kamino.CnNvZzeBXiLxUmA6b5eP4MYsNCjfeXxDWMDVJtgZpAtU.EVbyPKrHG6WBfm4dLxLMJpUDY43cCAcHSpV3KYjKsktW",
          "providerId": "kamino",
          "type": "lending",
          "marketId": "kamino.EVbyPKrHG6WBfm4dLxLMJpUDY43cCAcHSpV3KYjKsktW",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 0.01643327,
              "amountUsd": 4.5
            }
          ]
        },
        {
          "id": "kamino.3YWBQnwgi7FE7e7Xahuea2eiM8aPAv84nHoAvWUtm2QV.F22tnLsbv66vEU2GZRc7coaqZsr8UcBbyp9V2kqWAiWK",
          "providerId": "kamino",
          "type": "lending",
          "marketId": "kamino.F22tnLsbv66vEU2GZRc7coaqZsr8UcBbyp9V2kqWAiWK",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 0.32602,
              "amountUsd": 0.33
            }
          ]
        },
        {
          "id": "kamino.EYqpfGinjQfcDkKvn7HWTGbxcrCZpeL9pSKgqhgWtAJg.Atj6UREVWa7WxbF2EMKNyfmYUY1U1txughe2gjhcPDCo",
          "providerId": "kamino",
          "type": "lending",
          "marketId": "kamino.Atj6UREVWa7WxbF2EMKNyfmYUY1U1txughe2gjhcPDCo",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 1.013233,
              "amountUsd": 1.01
            }
          ]
        },
        {
          "id": "kamino.CnNvZzeBXiLxUmA6b5eP4MYsNCjfeXxDWMDVJtgZpAtU.d4A2prbA2whesmvHaL88BH6Ewn5N4bTSU2Ze8P6Bc4Q",
          "providerId": "kamino",
          "type": "lending",
          "marketId": "kamino.d4A2prbA2whesmvHaL88BH6Ewn5N4bTSU2Ze8P6Bc4Q",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 0.012468525,
              "amountUsd": 2.76
            }
          ]
        }
      ]
    }
  }
  ```
</Accordion>

Each position includes:

| Field        | Description                                                                                                          |
| ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `id`         | Unique position identifier                                                                                           |
| `providerId` | Protocol providing the market (e.g., `lulo`, `jupiter`, `kamino`)                                                    |
| `type`       | Position type (`yield`, `lending`, `loop`, `perpetual`)                                                              |
| `marketId`   | Market identifier within the protocol                                                                                |
| `history`    | Array of historical snapshots with `timestamp`, `amount`, and `amountUsd` (limited to 1000 data points per position) |

## Resolution

Resolution let's you control the time interval between data points. This is especially useful if you plan to use the data for charting or analytics.

### Available Options

| Resolution | Interval  | Best For                                          |
| ---------- | --------- | ------------------------------------------------- |
| `1m`       | 1 minute  | Real-time monitoring, very short-term analysis    |
| `5m`       | 5 minutes | Short-term tracking, recent activity              |
| `1h`       | 1 hour    | Daily analysis, medium-term trends                |
| `1d`       | 1 day     | Long-term portfolio tracking, historical analysis |

### Usage

To use resolution, you need to specify the time interval you want to use. For example, to get hourly snapshots, you would use the `1h` resolution.

```typescript {7} theme={null}
// Hourly snapshots example
const response = await fetch(
  'https://markets.dial.to/api/v0/positions/history?' + new URLSearchParams({
    walletAddress: '6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176',
    startTime: '2025-10-08T00:00:00Z',
    endTime: '2025-10-09T23:59:59Z',
    resolution: '1h'
  }),
  {
    headers: {
      'x-dialect-client-key': 'YOUR_CLIENT_KEY'
    }
  }
);
```

<Info>
  **Note:** Each position's history is limited to 1000 data points. Using appropriate resolution values helps you stay within this limit for longer time ranges.
</Info>

## Understanding Cumulative Values

Historical data tracks **cumulative values** - the actual balance in each position at each point in time.

### What This Means

When you look at historical snapshots, the `amount` and `amountUsd` values reflect:

* **Yield** - Accumulated interest earned on deposits
* **Deposits** - When you add funds to a position
* **Withdrawals** - When you remove funds from a position

### Example: Deposits

Here's real data from a Lulo position showing a deposit:

```json theme={null}
// October 8, 2025 - Initial snapshot
{
  "timestamp": "2025-10-08T16:24:29.000Z",
  "amount": 1.018845,
  "amountUsd": 1.02
}

// October 9, 2025 - After a deposit
{
  "timestamp": "2025-10-09T21:16:12.000Z",
  "amount": 2.017082,
  "amountUsd": 2.02
}
```

The jump in the example from \~1.02 to \~2.02 USDC between these two snapshots reflects a deposit action.

## Practical Examples

### Example 1: Calculate Total Portfolio Value

Sum up all position values across protocols:

```typescript theme={null}
const response = await fetch(
  'https://markets.dial.to/api/v0/positions/history?walletAddress=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176&startTime=2025-10-08T00:00:00Z&endTime=2025-10-10T23:59:59Z',
  {
    headers: {
      'x-dialect-client-key': 'YOUR_CLIENT_KEY'
    }
  }
);

const result = await response.json();

// Calculate total portfolio value in USD
const totalValueUsd = result.data.positions.reduce((total, position) => {
  const latestSnapshot = position.history[position.history.length - 1];
  return total + (latestSnapshot?.amountUsd || 0);
}, 0);

console.log(`Total portfolio value: $${totalValueUsd.toFixed(2)}`);
```

**Output:**

```
Total portfolio value: $18.79
```

### Example 2: Track Specific Position Over Time

Filter for a single position to see its growth:

```typescript theme={null}
const response = await fetch(
  'https://markets.dial.to/api/v0/positions/history?' + new URLSearchParams({
    walletAddress: '6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176',
    startTime: '2025-10-08T00:00:00Z',
    endTime: '2025-10-10T23:59:59Z',
    'positionIds[]': 'lulo.regular.HwE39BAt5i6ymd8hhZbaxTrYf61ifm8PRwJpm4o9ULzj'
  }),
  {
    headers: {
      'x-dialect-client-key': 'YOUR_CLIENT_KEY'
    }
  }
);

const result = await response.json();
const position = result.data.positions[0];

// Show growth over time
position.history.forEach(snapshot => {
  console.log(`${snapshot.timestamp}: ${snapshot.amount} USDC ($${snapshot.amountUsd})`);
});
```

**Output:**

```
2025-10-08T16:24:29.000Z: 1.018845 USDC ($1.02)
2025-10-09T21:16:12.000Z: 2.017082 USDC ($2.02)
```

### Example 3: Compare Positions Across Protocols

See how different protocol positions have performed:

```typescript theme={null}
const response = await fetch(
  'https://markets.dial.to/api/v0/positions/history?walletAddress=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176&startTime=2025-10-08T00:00:00Z&endTime=2025-10-10T23:59:59Z',
  {
    headers: {
      'x-dialect-client-key': 'YOUR_CLIENT_KEY'
    }
  }
);

const result = await response.json();

// Group by provider
const byProvider = result.data.positions.reduce((acc, position) => {
  const provider = position.providerId;
  const latestSnapshot = position.history[position.history.length - 1];

  if (!acc[provider]) {
    acc[provider] = { totalUsd: 0, positions: 0 };
  }

  acc[provider].totalUsd += latestSnapshot?.amountUsd || 0;
  acc[provider].positions += 1;

  return acc;
}, {});

console.log(byProvider);
```

**Output:**

```json theme={null}
{
  "lulo": { "totalUsd": 4.02, "positions": 2 },
  "jupiter": { "totalUsd": 6.17, "positions": 5 },
  "kamino": { "totalUsd": 8.6, "positions": 4 }
}
```

## API Playground

<Card title="Test the API" href="/api-reference/positions/get-historical-position-snapshots" icon="bolt">
  Play with the API and see the results in real-time.
</Card>


# Markets and Positions (Beta)
Source: https://docs.dialect.to/markets/index

Real-time market data and position tracking from Solana's top protocols with ready-to-use Blinks for seamless DeFi interactions.

Get information on markets and positions from across the Solana ecosystem, including APYs, TVL, LP fees, position data, and blockchain link URLs for key actions like Deposit and Withdraw.

<img alt="Markets Beta - Real-time market data dashboard" />

The Markets and Positions product is in beta, starting today with lending markets and positions. For more information on upcoming additional market types, or to submit a market type request, reach out to us at [hello@dialect.to](mailto:hello@dialect.to).

## Key Features

<CardGroup>
  <Card title="Fresh Updates" icon="clock">
    Our market data is updated every 10 minutes.
  </Card>

  <Card title="Multi-Protocol Support" icon="building-columns">
    Unified data format across Solana's top DeFi protocols.
  </Card>

  <Card title="Blinks Integration" icon="bolt">
    Ready-to-sign transaction URLs - no need to learn individual protocol SDKs.
  </Card>

  <Card title="Complete Market Data" icon="chart-bar">
    APY rates, deposits, borrows, limits, token metadata, and protocol data.
  </Card>
</CardGroup>

## What it does

Markets and Positions delivers extensive JSON documents containing:

* **Real-time lending rates** - Current deposit and borrow APYs for all markets
* **Position data** - Individual wallet positions across supported protocols
* **Market liquidity data** - Total deposits, borrows, and available capacity
* **Token information** - Token addresses, symbols, and decimal precision
* **Market limits** - Maximum deposit and borrow amounts per market
* **Ready-to-use Blinks** - Pre-built transaction URLs for deposits and withdrawals

## Get Started

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/markets/quick-start">
    Learn how to use and transform market data into instant DeFi actions
  </Card>

  <Card title="Try the API" icon="arrow-right" href="/api-reference/markets/list-all-markets">
    Try the **List all markets** endpoint to get real-time lending rates.
  </Card>
</CardGroup>


# Introduction
Source: https://docs.dialect.to/markets/market-types/introduction

Get real-time market data in a unified format across Solana's top DeFi protocols.

<img alt="Markets Overview" />

Every protocol has its own developer tools, market types, wording, and structure. Understanding each of these and building the right integrations is time-consuming and requires a lot of research.

Our Markets and Positions APIs solve this problem by providing a **unified format** across all [supported protocols](/markets/supported-protocols). We fetch, parse, and normalize this data so you can retrieve it in a single HTTP request. No specific protocol or web3 knowledge is required.

**We support the following market types:**

<CardGroup>
  <Card title="Yield" icon="chart-line-up" href="/markets/market-types/yield">
    Earn returns on deposited assets through DeFi strategies
  </Card>

  <Card title="Lending" icon="hand-holding-dollar" href="/markets/market-types/lending">
    Lend assets to earn interest or borrow against them
  </Card>

  <Card title="Loop" icon="arrows-rotate" href="/markets/market-types/loop">
    Leverage positions through repeated borrowing and lending
  </Card>

  <Card title="Perpetual" icon="infinity" href="/markets/market-types/perpetual">
    Trade perpetual futures with leverage
  </Card>

  <Card title="Prediction" icon="crystal-ball" href="/markets/market-types/prediction">
    Bet on outcomes of real-world events
  </Card>
</CardGroup>


# Lending Markets
Source: https://docs.dialect.to/markets/market-types/lending

Get Solana's top lending markets with real-time data and ready-to-use Blinks for seamless DeFi interactions.

<img alt="Lending Market Details" />

Lending markets allow users to deposit assets and earn interest or borrow against them. Unlike [yield markets](/markets/market-types/yield) where returns come from DeFi strategies, lending markets generate returns through borrower interest payments and optional protocol rewards.

Our Markets API already contains lots of information that you would manually collect via multiple API calls throughout protocols and providers, such as:

* basic protocol information (one call contains multiple protocols),
* deposit and borrow APY information,
* token information,
* protocol rewards,
* LTV and liquidation parameters,
* actions (deposit, withdraw, borrow, repay), etc.

By enriching the response with all of this information, it makes the API powerful enough to drive full-fledged dashboards and applications as well as smaller widgets, cards or notifications - All in a single API call!

## Supported Protocols

Our Markets API provides unified access to lending markets across multiple protocols:

* [**Kamino Borrow**](https://kamino.com/borrow)
* [**MarginFi**](https://marginfi.com/)
* [**Jupiter Lend**](https://jup.ag/lend/borrow)

If you want more information on the protocols that are supported, please refer to the [Supported Protocols Section](/markets/supported-protocols) page.

### Lending vs Yield

Lending markets differ from yield markets in how they generate returns and what functionality they offer. Below is a comparison of the two:

| Feature               | Lending Markets                                          | Yield Markets                              |
| --------------------- | -------------------------------------------------------- | ------------------------------------------ |
| **Primary Action**    | Deposit to lend, with borrowing option                   | Deposit to earn                            |
| **Return Source**     | Borrower interest payments + protocol rewards (optional) | Earnings collected through DeFi strategies |
| **Collateralization** | Required for borrowing                                   | Not required                               |
| **Risk Profile**      | Credit risk + liquidation risk (if assets were borrowed) | Strategy-dependent                         |
| **Composability**     | Two-sided (lend + borrow)                                | Mostly single-sided                        |

## Data Structure

Below is an example of a lending market response from the Markets API. Based on customer demand, we may add more fields to the response in the future.

For the latest data structure, please have a look at our [Markets API Reference](/api-reference/markets/list-all-markets) page.

<Note>
  Please note that we do our best to design our APIs to be non-breaking. It is
  recommended to filter the response and only include the fields / types you
  need to ensure it won't break your application if new fields are added over
  time.
</Note>

```json Lending Markets Data Structure theme={null}
{
  "id": "string",                    // Unique market identifier
  "type": "lending",                 // Market type
  "provider": {
    "id": "string",                  // Protocol identifier
    "name": "string",                // Protocol display name
    "icon": "string"                 // Protocol icon URL
  },
  "token": {
    "address": "string",             // Token mint address
    "symbol": "string",              // Token symbol
    "decimals": number,              // Token decimals
    "icon": "string"                 // Token icon URL
  },
  "websiteUrl": "string",            // Direct link to protocol (optional)

  // Deposit APY metrics
  "depositApy": number,              // Total deposit APY including rewards
  "baseDepositApy": number,          // Base deposit APY without rewards
  "baseDepositApy30d": number,       // Historical 30-day average (optional)
  "baseDepositApy90d": number,       // Historical 90-day average (optional)
  "baseDepositApy180d": number,      // Historical 180-day average (optional)

  // Borrow APY metrics
  "borrowApy": number,               // Total borrow APY including rewards
  "baseBorrowApy": number,           // Base borrow APY without rewards
  "baseBorrowApy30d": number,        // Historical 30-day average (optional)
  "baseBorrowApy90d": number,        // Historical 90-day average (optional)
  "baseBorrowApy180d": number,       // Historical 180-day average (optional)

  // Market metrics
  "totalDeposit": number,            // Total deposited (token amount)
  "totalDepositUsd": number,         // Total deposited (USD value)
  "totalBorrow": number,             // Total borrowed (token amount)
  "totalBorrowUsd": number,          // Total borrowed (USD value)
  "maxDeposit": number,              // Maximum deposit limit
  "maxBorrow": number,               // Maximum borrow limit

  // Risk parameters
  "maxLtv": number,                  // Maximum loan-to-value ratio
  "liquidationLtv": number,          // LTV threshold for liquidation

  "rewards": [                       // Additional reward tokens (optional)
    {
      "type": "deposit",
      "apy": number,
      "token": {
        "address": "string",
        "symbol": "string",
        "decimals": number,
        "icon": "string"
      },
      "marketAction": "deposit"
    }
  ],
  "additionalData": {},              // Protocol-specific metadata (varies by market)
  "actions": {
    "deposit": {
      "blinkUrl": "string"           // Blink action URL
    },
    "withdraw": {
      "blinkUrl": "string"           // Blink action URL
    },
    "borrow": {
      "blinkUrl": "string"           // Blink action URL
    },
    "repay": {
      "blinkUrl": "string"           // Blink action URL
    },
    "repayWithCollateral": {
      "blinkUrl": "string"           // Blink action URL (optional)
    },
    "claimRewards": {
      "blinkUrl": "string"           // Blink action URL (optional)
    }
  }
}
```

## Practical Example

In order to better understand how the API works, let's walk through an example response for the Kamino USDS Main Market below:

```json API Response for Kamino USDS Main Market theme={null}
{
  "id": "kamino.BHUi32TrEsfN2U821G4FprKrR4hTeK4LCWtA3BFetuqA",
  "type": "lending",
  "provider": {
    "id": "kamino",
    "name": "Kamino",
    "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/5cddfb2e-c98e-4734-528b-b541fb5e2b00/public"
  },
  "token": {
    "address": "USDSwr9ApdHk5bvJKMjzff41FfuX8bSxdKcR81vTwcA",
    "symbol": "USDS",
    "decimals": 6,
    "icon": "https://ipfs.io/ipfs/QmTW9HWfb2wsQqEVJiixkQ73Nsfp2Rx4ESaDSiQ7ThwnFM"
  },
  "websiteUrl": "https://kamino.com/borrow/reserve/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/BHUi32TrEsfN2U821G4FprKrR4hTeK4LCWtA3BFetuqA",
  "depositApy": 0.0534,
  "baseDepositApy": 0.0135,
  "baseDepositApy30d": 0.011462369546395708,
  "baseDepositApy90d": 0.01872287925720142,
  "baseDepositApy180d": 0.025712013041794924,
  "borrowApy": 0.0448,
  "baseBorrowApy": 0.0448,
  "baseBorrowApy30d": 0.04556353915804009,
  "baseBorrowApy90d": 0.050836781389652266,
  "baseBorrowApy180d": 0.058634378885015534,
  "totalDeposit": 22894432.359652,
  "totalDepositUsd": 22887415.9,
  "totalBorrow": 8751652.322147,
  "totalBorrowUsd": 8748970.2,
  "maxDeposit": 150000000,
  "maxBorrow": 140000000,
  "rewards": [
    {
      "type": "deposit",
      "apy": 0.0399,
      "token": {
        "address": "USDSwr9ApdHk5bvJKMjzff41FfuX8bSxdKcR81vTwcA",
        "symbol": "USDS",
        "decimals": 6,
        "icon": "https://ipfs.io/ipfs/QmTW9HWfb2wsQqEVJiixkQ73Nsfp2Rx4ESaDSiQ7ThwnFM"
      },
      "marketAction": "deposit"
    }
  ],
  "maxLtv": 0.8,
  "liquidationLtv": 0.9,
  "additionalData": {
    "marketAddress": "7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF",
    "reserveAddress": "BHUi32TrEsfN2U821G4FprKrR4hTeK4LCWtA3BFetuqA",
    "marketName": "Main Market"
  },
  "actions": {
    "deposit": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lending/reserve/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/BHUi32TrEsfN2U821G4FprKrR4hTeK4LCWtA3BFetuqA/deposit"
    },
    "withdraw": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lending/reserve/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/BHUi32TrEsfN2U821G4FprKrR4hTeK4LCWtA3BFetuqA/withdraw"
    },
    "borrow": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lending/reserve/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/BHUi32TrEsfN2U821G4FprKrR4hTeK4LCWtA3BFetuqA/borrow"
    },
    "repay": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lending/reserve/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/BHUi32TrEsfN2U821G4FprKrR4hTeK4LCWtA3BFetuqA/repay"
    },
    "repayWithCollateral": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lending/reserve/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/BHUi32TrEsfN2U821G4FprKrR4hTeK4LCWtA3BFetuqA/repay-with-collateral"
    },
    "claimRewards": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lending/reserve/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/BHUi32TrEsfN2U821G4FprKrR4hTeK4LCWtA3BFetuqA/claim-rewards"
    }
  }
}
```

### Understanding the Response

What you can see here is the original response from the API. As mentioned in the introduction section, this response is powerful enough to drive full-fledged dashboards and applications.

Let's break it down into its components:

* **Market Identity:**

  * `id`: Unique identifier combining protocol and reserve address
  * `type`: Market category (always `lending` for lending markets)
  * `provider`: Protocol information for branding in your UI
  * `token`: Full token information including address, symbol, decimals and icon
  * `websiteUrl`: Direct link to the market on the protocol's website

* **Deposit APY Breakdown:**

  * `depositApy` (5.46%) — Total combined deposit yield including rewards
  * `baseDepositApy` (1.38%) — Core yield from borrower interest
  * `baseDepositApy30d` (1.16%) — Historical 30-day average
  * `baseDepositApy90d` (1.95%) — Historical 90-day average
  * `baseDepositApy180d` (2.65%) — Historical 180-day average
  * `rewards` array (4.09% USDS) — Additional incentive tokens for depositors

* **Borrow APY Breakdown:**

  * `borrowApy` (4.48%) — Total cost to borrow (can be reduced by rewards)
  * `baseBorrowApy` (4.48%) — Base borrowing cost
  * `baseBorrowApy30d` (4.57%) — Historical 30-day average
  * `baseBorrowApy90d` (5.17%) — Historical 90-day average
  * `baseBorrowApy180d` (5.96%) — Historical 180-day average

* **Market Metrics:**

  * `totalDeposit` / `totalDepositUsd`: This market holds \$22.4M USDS in deposits
  * `totalBorrow` / `totalBorrowUsd`: \$8.7M USDS currently borrowed
  * `maxDeposit`: Maximum deposit cap (150M)
  * `maxBorrow`: Maximum borrow cap (140M)

  **Note:** `totalDepositUsd` and `totalBorrowUsd` are USD values, the rest are native token units.

* **Risk Parameters:**

  * `maxLtv` (80%) — Maximum loan-to-value ratio for borrowing
  * `liquidationLtv` (90%) — LTV threshold that triggers liquidation
  * `liquidationPenalty` — Penalty applied during liquidation (when available)

* **Actions:** The `actions` object contains Blink URLs for `deposit`, `withdraw`, `borrow`, `repay`, and optionally `repayWithCollateral` and `claimRewards` depending on the protocol.

* **Additional Data:** The `additionalData` object contains protocol-specific metadata. In this example, we have the following additional data for the Kamino USDS Main Market:
  * `marketAddress`: The address of the lending market
  * `reserveAddress`: The address of the reserve
  * `marketName`: The name of the market

### Protocol-Specific Additional Data

The `additionalData` field varies by provider. In our example, we have the following additional data for Kamino Lend:

```json Kamino Borrow theme={null}
{
  "additionalData": {
    "marketAddress": "7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF",
    "reserveAddress": "BHUi32TrEsfN2U821G4FprKrR4hTeK4LCWtA3BFetuqA",
    "marketName": "Main Market"
  }
}
```

MarginFi returns a `groupAddress` in the additional data:

```json MarginFi theme={null}
{
  "additionalData": {
    "groupAddress": "4qp6Fx6tnZkY5Wropq9wUYgtFxXKwE6viZxFHg3rdAG8"
  }
}
```

Jupiter Lend markets may include a `borrowToken` field at the root level when the borrowed token differs from the collateral token:

```json Jupiter Borrow (with borrowToken) theme={null}
{
  "token": {
    "address": "So11111111111111111111111111111111111111112",
    "symbol": "WSOL",
    "decimals": 9,
    "icon": "https://coin-images.coingecko.com/coins/images/21629/large/solana.jpg?1696520989"
  },
  "borrowToken": {
    "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "symbol": "USDC",
    "decimals": 6,
    "icon": "https://coin-images.coingecko.com/coins/images/6319/large/usdc.png?1696506694"
  }
}
```

As we continue to add more providers and markets, the `additionalData` field will continue to grow and be more powerful. If you need more information or want to check out what protocols are supported, please refer to the [Supported Protocols](/markets/supported-protocols) page.


# Loop Markets
Source: https://docs.dialect.to/markets/market-types/loop

Get real-time market data for loop markets in a unified format across Solana's top DeFi protocols.

<img alt="Loop Market Details View" />

Loop markets (also known as "Multiply") allow users to create leveraged positions by repeatedly depositing collateral and borrowing against it in an automated way.

Our Markets API already contains lots of information that you would manually collect via multiple API calls throughout protocols and providers, such as:

* basic protocol information,
* leverage and APY information,
* token pair information (collateral and debt tokens),
* risk parameters (LTV and liquidation thresholds),
* actions (setup, deposit, withdraw), etc.

By enriching the response with all of this information, it makes the API powerful enough to drive full-fledged dashboards and applications as well as smaller widgets, cards or notifications - All in a single API call!

## How Loop Markets Work

Loop markets automate a looping strategy, which is as follows:

<Steps>
  <Step title="Choose Leverage & Deposit">
    The user chooses the desired leverage level and deposits collateral (Token
    A) into the market
  </Step>

  <Step title="Borrow">
    The protocol borrows against the deposited collateral (Token B)
  </Step>

  <Step title="Swap & Re-deposit">
    The borrowed amount gets swapped back to Token A and gets re-deposited
  </Step>

  <Step title="Repeat">
    This cycle repeats automatically until the user's chosen leverage level is
    reached
  </Step>
</Steps>

This creates a leveraged position that amplifies exposure to the collateral asset while borrowing the debt asset. The APY reflects the net return after accounting for borrowing costs and the yield from the collateral asset.

## Data Structure

Below is an example of a loop market response from the Markets API. Based on customer demand, we may add more fields to the response in the future.

For the latest data structure, please have a look at our [Markets API Reference](/api-reference/markets/list-all-markets) page.

<Note>
  Please note that we do our best to design our APIs to be non-breaking. It is
  recommended to filter the response and only include the fields / types you
  need to ensure it won't break your application if new fields are added over
  time.
</Note>

```json Loop Markets Data Structure theme={null}
{
  "id": "string",                    // Unique market identifier
  "type": "loop",                    // Market type
  "provider": {
    "id": "string",                  // Protocol identifier
    "name": "string",                // Protocol display name
    "icon": "string"                 // Protocol icon URL
  },
  "tokenA": {                        // Collateral token
    "address": "string",             // Token mint address
    "symbol": "string",              // Token symbol
    "decimals": number,              // Token decimals
    "icon": "string"                 // Token icon URL
  },
  "tokenB": {                        // Debt/borrow token
    "address": "string",             // Token mint address
    "symbol": "string",              // Token symbol
    "decimals": number,              // Token decimals
    "icon": "string"                 // Token icon URL
  },
  "websiteUrl": "string",            // Direct link to protocol (optional)
  "depositApy": number,              // Net APY after leverage and borrowing costs
  "maxLeverage": number,             // Maximum leverage multiplier (e.g., 7.69x)
  "maxLtv": number,                  // Maximum loan-to-value ratio (0-1)
  "liquidationLtv": number,          // LTV threshold for liquidation (0-1)
  "additionalData": {},              // Protocol-specific metadata (varies by market)
  "actions": {
    "setup": {
      "blinkUrl": "string"           // Blink URL for LUT creation
    },
    "deposit": {
      "blinkUrl": "string"           // Blink URL for leveraged deposit
    },
    "withdraw": {
      "blinkUrl": "string"           // Blink URL for position withdrawal
    }
  }
}
```

## Practical Example

In order to better understand how the API works, let's walk through an example response for the Kamino Multiply lanternSOL/SOL strategy below:

```json API Response for Kamino Multiply lanternSOL/SOL theme={null}
{
  "id": "kamino.multiply.J5oj3VKWQNKRZx3heWZx7JZC59AEDQ9UQwqqiy63nCuf.d4A2prbA2whesmvHaL88BH6Ewn5N4bTSU2Ze8P6Bc4Q",
  "type": "loop",
  "provider": {
    "id": "kamino",
    "name": "Kamino",
    "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/5cddfb2e-c98e-4734-528b-b541fb5e2b00/public"
  },
  "tokenA": {
    "address": "LnTRntk2kTfWEY6cVB8K9649pgJbt6dJLS1Ns1GZCWg",
    "symbol": "lanternSOL",
    "decimals": 9,
    "icon": "https://arweave.net/juI8rxciTff6pljaDiXMEq5klSOngQol_8lvyokGGwY"
  },
  "tokenB": {
    "address": "So11111111111111111111111111111111111111112",
    "symbol": "SOL",
    "decimals": 9,
    "icon": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png"
  },
  "websiteUrl": "https://kamino.com/multiply/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/J5oj3VKWQNKRZx3heWZx7JZC59AEDQ9UQwqqiy63nCuf/d4A2prbA2whesmvHaL88BH6Ewn5N4bTSU2Ze8P6Bc4Q",
  "depositApy": 0.1902,
  "maxLeverage": 7.692307692307692,
  "maxLtv": 0.87,
  "liquidationLtv": 0.92,
  "additionalData": {
    "marketAddress": "7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF",
    "collateralReserveAddress": "J5oj3VKWQNKRZx3heWZx7JZC59AEDQ9UQwqqiy63nCuf",
    "borrowReserveAddress": "d4A2prbA2whesmvHaL88BH6Ewn5N4bTSU2Ze8P6Bc4Q"
  },
  "actions": {
    "setup": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/multiply/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/setup?collTokenMint=LnTRntk2kTfWEY6cVB8K9649pgJbt6dJLS1Ns1GZCWg&debtTokenMint=So11111111111111111111111111111111111111112"
    },
    "deposit": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/multiply/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/deposit?collTokenMint=LnTRntk2kTfWEY6cVB8K9649pgJbt6dJLS1Ns1GZCWg&debtTokenMint=So11111111111111111111111111111111111111112"
    },
    "withdraw": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/multiply/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/withdraw?collTokenMint=LnTRntk2kTfWEY6cVB8K9649pgJbt6dJLS1Ns1GZCWg&debtTokenMint=So11111111111111111111111111111111111111112"
    }
  }
}
```

### Understanding the Response

What you can see here is the original response from the API. As mentioned in the introduction section, this response is powerful enough to drive full-fledged dashboards and applications.

Let's break it down into its components:

* **Market Identity:**

  * `id`: Unique identifier combining protocol, market type, and reserve addresses
  * `type`: Market category (always `loop` for loop markets)
  * `provider`: Protocol information for branding in your UI
  * `tokenA`: Collateral token (lanternSOL) - the asset you want leveraged exposure to
  * `tokenB`: Debt token (SOL) - the asset being borrowed
  * `websiteUrl`: Direct link to the loop strategy on the protocol's website

* **APY:**

  * `depositApy` (19.04%) — Net APY after accounting for leverage and borrowing costs

  **Note:** This represents the leveraged yield. For example, if lanternSOL yields 5% and SOL borrowing costs 3%, with 7x leverage, the net APY reflects: (5% × 7) - (3% × 6) = approximately 17% before fees.

* **Leverage Parameters:**

  * `maxLeverage` (7.69x) — Maximum leverage multiplier available for this strategy
  * `maxLtv` (0.87 or 87%) — Maximum loan-to-value ratio allowed when establishing the leveraged position
  * `liquidationLtv` (0.92 or 92%) — LTV threshold at which the position becomes eligible for liquidation

* **Actions:** The `actions` object contains Blink URLs for:

  * **`setup`** — Creates a Lookup Table (LUT) required before opening a leveraged position. This is a one-time setup per wallet for each market.
  * **`deposit`** — Opens or increases a leveraged position by depositing collateral and executing the looping strategy.
  * **`withdraw`** — Reduces or closes a leveraged position by unwinding the loop and returning collateral.

* **Additional Data:** The `additionalData` object contains protocol-specific metadata. In this example, we have the following additional data for Kamino Multiply:
  * `marketAddress`: The address of the lending market
  * `collateralReserveAddress`: The reserve address for the collateral token (lanternSOL)
  * `borrowReserveAddress`: The reserve address for the borrow token (SOL)


# Perpetual Markets
Source: https://docs.dialect.to/markets/market-types/perpetual

Get real-time market data for perpetual leverage positions in a unified format across Solana's top DeFi protocols.

<img alt="Perpetual Market Details View" />

Perpetual markets (also known as "Leverage" markets) allow users to take leveraged long or short positions on asset pairs.

Our Markets API already contains lots of information that you would manually collect via multiple API calls throughout protocols and providers, such as:

* basic protocol information,
* liquidity and leverage information,
* token pair information (long and short tokens),
* available actions (setup, open position, close position), etc.

By enriching the response with all of this information, it makes the API powerful enough to drive full-fledged dashboards and applications as well as smaller widgets, cards or notifications - All in a single API call!

## Supported Protocols

Our Markets API provides unified access to perpetual markets across multiple protocols:

* [**Kamino Leverage**](https://kamino.com/leverage)

If you want more information on the protocols that are supported, please refer to the [Supported Protocols Section](/markets/supported-protocols) page.

## Data Structure

Below is an example of a perpetual market response from the Markets API. Based on customer demand, we may add more fields to the response in the future.

For the latest data structure, please have a look at our [Markets API Reference](/api-reference/markets/list-all-markets) page.

<Note>
  Please note that we do our best to design our APIs to be non-breaking. It is
  recommended to filter the response and only include the fields / types you
  need to ensure it won't break your application if new fields are added over
  time.
</Note>

```json Perpetual Markets Data Structure theme={null}
{
  "id": "string",                    // Unique market identifier
  "type": "perpetual",               // Market type
  "provider": {
    "id": "string",                  // Protocol identifier
    "name": "string",                // Protocol display name
    "icon": "string"                 // Protocol icon URL
  },
  "tokenA": {                        // Base token (asset being traded)
    "address": "string",             // Token mint address
    "symbol": "string",              // Token symbol
    "decimals": number,              // Token decimals
    "icon": "string"                 // Token icon URL
  },
  "tokenB": {                        // Quote token
    "address": "string",             // Token mint address
    "symbol": "string",              // Token symbol
    "decimals": number,              // Token decimals
    "icon": "string"                 // Token icon URL
  },
  "websiteUrl": "string",            // Direct link to protocol (optional)
  "liquidity": {
    "longUsd": number,               // Total liquidity available for long positions (USD)
    "shortUsd": number               // Total liquidity available for short positions (USD)
  },
  "maxLeverage": number,             // Maximum leverage multiplier (e.g., 3.85x)
  "additionalData": {},              // Protocol-specific metadata (varies by market)
  "actions": {
    "setup": {
      "blinkUrl": "string"           // Blink URL for LUT creation
    },
    "openPosition": {
      "blinkUrl": "string"           // Blink URL to open a leveraged position
    },
    "closePosition": {
      "blinkUrl": "string"           // Blink URL to close an open position
    }
  }
}
```

## Practical Example

In order to better understand how the API works, let's walk through an example response for the Kamino Leverage SOL/USDC market below:

```json API Response for Kamino Leverage SOL/USDC theme={null}
{
  "id": "kamino.leverage.So11111111111111111111111111111111111111112.EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "type": "perpetual",
  "provider": {
    "id": "kamino",
    "name": "Kamino",
    "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/5cddfb2e-c98e-4734-528b-b541fb5e2b00/public"
  },
  "tokenA": {
    "address": "So11111111111111111111111111111111111111112",
    "symbol": "SOL",
    "decimals": 9,
    "icon": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png"
  },
  "tokenB": {
    "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "symbol": "USDC",
    "decimals": 6,
    "icon": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/logo.png"
  },
  "websiteUrl": "https://kamino.com/leverage/main/SOL/USDC",
  "liquidity": { "longUsd": 119915527.62, "shortUsd": 70570015 },
  "maxLeverage": 3.846153846153846,
  "actions": {
    "setup": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/leverage/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/setup?collTokenMint=So11111111111111111111111111111111111111112&debtTokenMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    },
    "openPosition": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/leverage/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/openPosition?collTokenMint=So11111111111111111111111111111111111111112&debtTokenMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    },
    "closePosition": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/leverage/7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF/closePosition?collTokenMint=So11111111111111111111111111111111111111112&debtTokenMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
  }
}
```

### Understanding the Response

What you can see here is the original response from the API. As mentioned in the introduction section, this response is powerful enough to drive full-fledged dashboards and applications.

Let's break it down into its components:

* **Market Identity:**

  * `id`: Unique identifier combining protocol, market type, and token addresses
  * `type`: Market category (always `perpetual` for perpetual markets)
  * `provider`: Protocol information for branding in your UI
  * `tokenA`: Base token (SOL) - the asset you're taking a leveraged position on
  * `tokenB`: Quote token (USDC) - the token used for pricing and collateral
  * `websiteUrl`: Direct link to the leverage market on the protocol's website

* **Liquidity:**

  * `longUsd` (\$119.9M) — Total liquidity available for long positions (betting SOL price will increase)
  * `shortUsd` (\$70.6M) — Total liquidity available for short positions (betting SOL price will decrease)

  **Note:** Unlike traditional perpetual futures that use funding rates, Kamino's Leverage positions work similarly to spot margin trading.

* **Leverage:**

  * `maxLeverage` (3.85x) — Maximum leverage multiplier available for this market

  **Example:** With \$1,000 and 3.85x leverage, you can control a position worth \$3,850.

* **Actions:** The `actions` object contains Blink URLs for:

  * **`setup`** — Creates a Lookup Table (LUT) required before opening a leveraged position. This is a one-time setup per wallet for each market.
  * **`openPosition`** — Opens a long or short leveraged position on the token pair.
  * **`closePosition`** — Closes an existing leveraged position and returns the remaining collateral.

* **Additional Data:** The `additionalData` object contains protocol-specific metadata (if available).


# Prediction Markets
Source: https://docs.dialect.to/markets/market-types/prediction

Get real-time market data for prediction markets on Solana.

<img alt="Prediction Market Details View" />

Prediction markets allow users to bet on the outcomes of real-world events. Users can buy "Yes" or "No" outcome tokens with the price of these tokens reflecting the market's collective belief about the likelihood of an event occurring.

Our Markets API provides all the information you need to build prediction market interfaces, including:

* basic protocol information,
* market title and status,
* bid/ask prices for Yes and No outcomes,
* trading volume and open interest,
* outcome tokens information,
* timing information (open, close, expirationTime), etc.

By enriching the response with all of this information, it makes the API powerful enough to drive full-fledged dashboards and applications as well as smaller widgets, cards or notifications - All in a single API call!

## Supported Protocols

Our Markets API currently supports prediction markets from [**DFlow**](https://dflow.net), who are the official provider for [Kalshi](https://kalshi.com).

If you want more information on the protocols that are supported or want to request more providers, please refer to the [Supported Protocols Section](/markets/supported-protocols) page.

## Understanding Events and Markets

![Expiration image for Prediction Markets and Events](https://res.cloudinary.com/dnxjhra4h/image/upload/v1769175373/prediction-events-and-markets_ticczm.png)
When working with prediction markets, it's important to understand the distinction between **events** and **markets**:

* **Markets** are the individual tradable outcomes within an event (e.g., "Democratic Party wins - Yes/No", "Republican Party wins - Yes/No")
* **Events** are groupings of markets (e.g., "Which party will win control of the US House in 2026?")

### Markets

A single event typically has multiple markets. In our example the question "Which party will win control of the US House in 2026?" will create two markets:

1. Market for the **Domocratic Party** (Yes/No) and
2. Market for the **Republican Party** (Yes/No).

For crypto specifially, it is often the case that each market gets multiple token markets on top:

* **CASH market** — For purchasing with Phantom's stable coin
* **USDC market** — For purchasing with USDC

Which means that the API will return 4 markets for this single event:

| Event                     | Markets                   | Token |
| ------------------------- | ------------------------- | ----- |
| Control of the House 2026 | Democratic Party (Yes/No) | USDC  |
|                           | Democratic Party (Yes/No) | CASH  |
|                           | Republican Party (Yes/No) | USDC  |
|                           | Republican Party (Yes/No) | CASH  |

### Events

The `bundleId` field is the key to grouping markets that belong to the same underlying event. All markets for the same question share the same `bundleId`, allowing you to:

* Display related bets together in your UI
* Create "position bundles" showing all positions for a single event
* Build event-centric dashboards similar to Kalshi's interface

### Example: Grouping Political Markets

Our API will return you four markets for the "Control of the House 2026" event. In order to make it easier for your users, it is recommended to group these markets by their `bundleId`. The example bleow illustrates this concept for the CASH markets:

```json {5, 13} Multiple markets with same bundleId theme={null}
// Market 1: Democratic Party (Cash)
{
  "id": "dflow.prediction.house-2026-dem-cash",
  "title": "Democratic Party will win control of US House",
  "bundleId": "house-control-2026",
  ...
}

// Market 2: Republican Party (Cash)
{
  "id": "dflow.prediction.house-2026-rep-cash",
  "title": "Republican Party will win control of US House",
  "bundleId": "house-control-2026",
  ...
}
```

All markets share the same `bundleId: "house-control-2026"`, indicating they belong to the same underlying event.

<Tip>
  To group markets by event in your application, filter or group the API
  response by the `bundleId` field. This recreates the "event" view from
  platforms like Kalshi.
</Tip>

```typescript Grouping Markets by Event theme={null}
// Group markets by event using bundleId
const marketsByEvent = markets.reduce((acc, market) => {
  const eventId = market.bundleId;
  if (!acc[eventId]) acc[eventId] = [];
  acc[eventId].push(market);
  return acc;
}, {});
```

## Data Structure

Below is an example of a prediction market response from the Markets API. Based on customer demand, we may add more fields to the response in the future.

For the latest data structure, please have a look at our [Markets API Reference](/api-reference/markets/list-all-markets) page.

<Note>
  Please note that we do our best to design our APIs to be non-breaking. It is
  recommended to filter the response and only include the fields / types you
  need to ensure it won't break your application if new fields are added over
  time.
</Note>

```json Prediction Markets Data Structure theme={null}
{
  "id": "string",                    // Unique market identifier
  "type": "prediction",              // Market type
  "provider": {
    "id": "string",                  // Protocol identifier
    "name": "string",                // Protocol display name
    "icon": "string"                 // Protocol icon URL
  },
  "title": "string",                 // Market question/title
  "subtitle": "string",              // Additional context (optional)
  "status": "open|closed|settled",   // Market status
  "result": "string",                // Outcome result (when settled)
  "volume": number,                  // Total trading volume (USD)
  "openInterest": number,            // Open interest (USD)
  "yesBid": number,                  // Best bid price for Yes outcome
  "yesAsk": number,                  // Best ask price for Yes outcome
  "noBid": number,                   // Best bid price for No outcome
  "noAsk": number,                   // Best ask price for No outcome
  "openTime": number,                // Unix timestamp when market opened
  "closeTime": number,               // Unix timestamp when trading closes
  "expirationTime": number,          // Unix timestamp when market expires
  "yesToken": {                      // Yes outcome token
    "address": "string",             // Token mint address
    "symbol": "string",              // Token symbol
    "decimals": number,              // Token decimals
    "icon": "string",                // Token icon URL
    "name": "string"                 // Token name
  },
  "noToken": {                       // No outcome token
    "address": "string",             // Token mint address
    "symbol": "string",              // Token symbol
    "decimals": number,              // Token decimals
    "icon": "string",                // Token icon URL
    "name": "string"                 // Token name
  },
  "websiteUrl": "string",            // Direct link to market on protocol
  "bundleId": "string",              // Groups markets from the same event
  "additionalData": {}               // Protocol-specific metadata
}
```

## Practical Example

In order to better understand how the API works, let's walk through an example response for a DFlow prediction market. This example shows a political prediction market for control of the U.S. House:

```json API Response for DFlow Prediction Market theme={null}
{
  "id": "dflow.prediction.CONTROLH-2026.G7EqT9zdoRKt5RScDhpKjryEnT2SVjAViBJb34smb6SH",
  "type": "prediction",
  "provider": {
    "id": "dflow",
    "name": "DFlow",
    "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/d5d0e3f9-72f3-4a19-a415-6994f32c1f00/public"
  },
  "title": "Will Republicans win the House in 2026?",
  "subtitle": "",
  "status": "open",
  "volume": 1858086,
  "openInterest": 1113892,
  "yesBid": 0.23,
  "yesAsk": 0.24,
  "noBid": 0.76,
  "noAsk": 0.77,
  "openTime": 1730905200,
  "closeTime": 1801494000,
  "expirationTime": 1801494000,
  "yesToken": {
    "address": "7Ady9N19XAAcqPLWwSe7ngPbxegMgvEQd55V4bR4jN2z",
    "symbol": "DFlowYU0114",
    "decimals": 6,
    "icon": "https://kalshi-public-docs.s3.amazonaws.com/series-images-webp/CONTROLH.webp",
    "name": "Yes Republican Party"
  },
  "noToken": {
    "address": "8XctSiRJZhLA6QaB3p61iZwE1PCTQbbhFaDSEufkwzDQ",
    "symbol": "DFlowNU0114",
    "decimals": 6,
    "icon": "https://kalshi-public-docs.s3.amazonaws.com/series-images-webp/CONTROLH.webp",
    "name": "No Republican Party"
  },
  "bundleId": "dflow.prediction.CONTROLH-2026",
  "additionalData": {
    "ticker": "CONTROLH-2026-R",
    "eventTicker": "CONTROLH-2026",
    "marketLedger": "G7EqT9zdoRKt5RScDhpKjryEnT2SVjAViBJb34smb6SH",
    "purchaseToken": {
      "icon": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/logo.png",
      "symbol": "USDC",
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "decimals": 6
    },
    "redemptionStatus": "pending"
  }
}
```

### Understanding the Response

What you can see here is the original response from the API. As mentioned in the introduction section, this response is powerful enough to drive full-fledged dashboards and applications.

Let's break it down into its components:

* **Market Identity:**
  * `id`: Unique identifier combining protocol, market type, and market slug
  * `type`: Market category (always `prediction` for prediction markets)
  * `provider`: Protocol information for branding in your UI
  * `title`: The market question users are betting on
  * `subtitle`: Additional context about the market (optional)
  * `websiteUrl`: Direct link to the market on the protocol's website

* **Market Status:**
  * `status`: Current state of the market
    * `open` — Market is active and accepting trades
    * `closed` — Trading has ended, awaiting settlement
    * `settled` — Outcome has been determined and payouts processed
  * `result`: The final outcome (only present when settled)

* **Pricing (Implied Probabilities):**

  * `yesBid` (0.23) / `yesAsk` (0.24) — Bid/ask prices for Yes tokens, implying \~23-24% probability
  * `noBid` (0.76) / `noAsk` (0.77) — Bid/ask prices for No tokens, implying \~76-77% probability

  **Note:** Prices represent implied probabilities. A Yes price of 0.23 means the market implies a 23% chance of the outcome occurring.

* **Market Metrics:**
  * `volume` (\$1.86M) — Total trading volume in USD
  * `openInterest` (\$1.11M) — Total value of outstanding positions

* **Timing:**
  * `openTime` — When the market opened for trading (Unix timestamp)
  * `closeTime` — When trading will close (Unix timestamp)
  * `expirationTime` — When the market will be settled (Unix timestamp)

* **Outcome Tokens:**
  * `yesToken` / `noToken` — Token information for each outcome, including mint addresses for on-chain interaction

* **Bundle ID:**
  * `bundleId` ("dflow\.prediction.CONTROLH-2026") — Groups markets belonging to the same underlying event. All markets with the same bundleId are related (e.g., different party outcomes for the same election, or the same market with different purchase tokens).

* **Additional Data:** The `additionalData` object contains protocol-specific metadata. See [Protocol-Specific Additional Data](#protocol-specific-additional-data) for details.

## Filtering Prediction Markets

If you are only interested in specific prediction markets, you can use the `filters` parameter to refine your API requests.

<video alt="Demo of filtering prediction markets via API parameters" />

<Note>
  Filters only work for `prediction` market type. Make sure to set this type
  before sending your request.
</Note>

As of now, we support filtering by the following status values:

* `open`
* `closed`
* `settled`

**Examples:**

* Open only: `{"prediction":{"status":["open"]}}`
* Exclude settled: `{"prediction":{"status":["open","closed"]}}`

If you need more filter options or want to request a feature, please reach out to us at [hello@dialect.to](mailto:hello@dialect.to).

## Tracking Prediction Positions

Our [Positions API](/api-reference/positions/list-all-market-positions-by-wallet-address) and [PnL API](/api-reference/positions/get-pnl-data-for-wallet-positions) give you everything you need to track a user's prediction market activity. Without them, tracking DFlow positions requires multiple steps:

1. Fetch all token accounts for a wallet
2. Get tokenized account mints
3. Use DFlow's endpoint to filter outcome token mints
4. Fetch market details for those mints

The Positions API simplifies this to a single call.

### Fetching Positions

Our Positions API is designed to return you all positions for a given wallet address. Then you can add the `type=prediction` parameter to filter the positions by market type.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch(
    'https://markets.dial.to/api/v0/positions/owners?walletAddresses=YOUR_WALLET&type=prediction',
    {
      headers: {
        'x-dialect-client-key': 'YOUR_CLIENT_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(data.positions);

  ```

  ```bash cURL theme={null}
  curl 'https://markets.dial.to/api/v0/positions/owners?walletAddresses=YOUR_WALLET&type=prediction' \
    --header 'x-dialect-client-key: YOUR_CLIENT_KEY'
  ```
</CodeGroup>

### Grouping Positions by Event

Use the `bundleId` field to group a user's positions that belong to the same underlying event:

```typescript Grouping Positions by Event theme={null}
// Group positions by event using bundleId
const positionsByEvent = positions.reduce((acc, position) => {
  const eventId = position.bundleId;
  if (!acc[eventId]) acc[eventId] = [];
  acc[eventId].push(position);
  return acc;
}, {});
```

### Filtering for Active Positions

By default, the Positions API returns all positions. To get only positions in markets that are still actively trading, filter by `market.status`:

```typescript Filtering for Active Positions theme={null}
// Filter for positions in open markets only
const activePositions = positions.filter(
  (position) => position.market.status === "open",
);
```

The `market.status` field indicates the current state of the market:

| Status    | Description                                             |
| --------- | ------------------------------------------------------- |
| `open`    | Market is active and accepting trades                   |
| `closed`  | Trading has ended, awaiting settlement                  |
| `settled` | Outcome has been determined, position may be redeemable |

<Tip>
  Server-side filtering for positions by status is coming soon via the `filters`
  parameter. For now, use client-side filtering as shown above.
</Tip>

If you need more filtering options, please reach out to us at [hello@dialect.to](mailto:hello@dialect.to).

### Cost Basis

The Positions API includes cost basis data for prediction market positions, giving you insight into a user's average entry price and total capital committed to a position. It answers the question: **“How much did I spend to acquire the tokens I currently hold?”**

Cost basis is calculated using the **average cost method**, which is the same approach used by traditional brokerages.

#### Response Fields

The following fields are included on each prediction position:

| Field            | Type     | Description                                                                 |
| ---------------- | -------- | --------------------------------------------------------------------------- |
| `costBasisTotal` | `number` | Total capital committed to the position (sum of all buys at their prices)   |
| `costBasisAvg`   | `number` | Average price paid per token (total cost basis divided by current quantity) |

#### Example Response

Here is an example of a prediction position response that includes cost basis data:

```json {15-18} Prediction Position with Cost Basis theme={null}
{
  "id": "dflow.prediction.KXNCAAMBGAME-26FEB13MASSAKR.GKmqm1hCPznFXK3Qku7y6PT2aDutRHiENvgT5mkkYzKf.yes.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "type": "prediction",
  "ownerAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "bundleId": "dflow.prediction.KXNCAAMBGAME-26FEB13MASSAKR",
  "marketId": "dflow.prediction.KXNCAAMBGAME-26FEB13MASSAKR.GKmqm1hCPznFXK3Qku7y6PT2aDutRHiENvgT5mkkYzKf",
  "token": {
    "address": "G5ntr63hgHAhJjNkJgfumexUDpVbz2z8FaoqRhnMxe9w",
    "symbol": "DFlowYC66dc",
    "decimals": 6,
    "icon": "https://kalshi-public-docs.s3.amazonaws.com/series-images-webp/KXNCAAMBGAME.webp",
    "name": "Yes Akron"
  },
  "side": "yes",
  "amount": 2,
  "amountUsd": 2,
  "costBasisTotal": 1.772609,
  "costBasisAvg": 0.8863045,
  "additionalData": {},
  "market": {
    // more market data
  }
}
```

In this example:

* The user holds **2 "Yes Akron" tokens** (`amount: 2`) worth **\$2.00** (`amountUsd: 2`)
* Their total capital committed is **\$1.77** (`costBasisTotal: 1.772609`)
* Their average entry price is **\$0.89 per token** (`costBasisAvg: 0.8863045`)
* Since the market settled as "yes" and each token pays out \$1.00, this position is profitable

#### How Cost Basis is Calculated

Cost basis tracks two values per position: the **total capital** (`costBasisTotal`) committed and the **average price per token** (`costBasisAvg`). These values evolve with every trade event:

|                      | Buy                         | Sell                             | Full Exit      |
| -------------------- | --------------------------- | -------------------------------- | -------------- |
| **Amount**           | + buy amount                | - sell amount                    | Resets to 0    |
| **Total Cost Basis** | + buy amount × buy price    | - sell amount × current avg cost | Resets to 0    |
| **Avg Cost Basis**   | Recomputed (total / amount) | Unchanged                        | Resets to null |

Note that the sell price does not affect cost basis. Sells are treated purely as inventory reductions at average cost. When quantity reaches zero (full exit), any subsequent buys are treated as a new position with no historical carryover.

**Transfers**

Besides trades, positions can also change through token transfers. Here is how transfers affect cost basis:

* **Inbound transfers** are treated as buy events at the current average cost basis. If no position exists yet (i.e., the transfer is the first event for this wallet), the current market price is used instead.
* **Outbound transfers** are treated as sell events, reducing both quantity and total cost basis.

**Example**

Here is a step-by-step example showing how cost basis evolves across multiple trades:

| Event                | Quantity | Total Cost Basis | Avg Cost Basis |
| -------------------- | -------- | ---------------- | -------------- |
| Buy 100 @ \$0.25     | 100      | \$25.00          | \$0.25         |
| Buy 50 @ \$0.40      | 150      | \$45.00          | \$0.30         |
| Sell 50 @ \$0.50     | 100      | \$30.00          | \$0.30         |
| Sell 100 (full exit) | 0        | \$0.00           | null           |
| Buy 200 @ \$0.60     | 200      | \$120.00         | \$0.60         |

Notice that after the full exit, the new buy starts fresh with no carryover from the previous trading episode.

### PnL

PnL allows the user to see how their positions are performing. It answers the question: **"Am I profitable or am I loosing money?"**

The [Positions API](/api-reference/positions/list-all-market-positions-by-wallet-address) returns PnL for **active positions** only. Once a user fully redeems their outcome tokens, the position is closed and no longer returned. Use the [PnL API](/api-reference/positions/get-pnl-data-for-wallet-positions) to access PnL across all positions, including closed ones.

#### Response Fields

Each prediction position includes a `pnl` object containing the following fields:

| Field              | Type     | Description                                              |
| ------------------ | -------- | -------------------------------------------------------- |
| `unrealized`       | `number` | Current gain or loss on shares still held                |
| `unrealizedPct`    | `number` | Unrealized PnL as a percentage                           |
| `realized`         | `number` | Profit or loss locked in from shares already sold        |
| `total`            | `number` | Combined PnL for the current position                    |
| `totalLifetime`    | `number` | Cumulative total PnL including already closed positions  |
| `realizedLifetime` | `number` | Cumulative realized PnL including fully closed positions |

<Note>
  `total` and `totalLifetime` differ when a user has fully exited and re-entered
  a position. `total` reflects the current open position only, while
  `totalLifetime` carries forward gains and losses from previous closed
  episodes.
</Note>

#### Example Response

```json {12-23} Prediction Position with PnL theme={null}
{
  "id": "dflow.prediction.KXFEDCHAIRNOM-29.6Ryen6J3RETCd4oqaViA6QsPxvxSPjLYxcPDLHa7qK19.yes.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "type": "prediction",
  "ownerAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "bundleId": "dflow.prediction.KXFEDCHAIRNOM-29",
  "marketId": "dflow.prediction.KXFEDCHAIRNOM-29.6Ryen6J3RETCd4oqaViA6QsPxvxSPjLYxcPDLHa7qK19",
  "side": "yes",
  "amount": 1,
  "amountUsd": 1,
  "costBasisTotal": 0.95,
  "costBasisAvg": 0.95,
  "pnl": {
    "unrealized": 0.05,
    "unrealizedPct": 0.0494,
    "realized": 0,
    "total": 0.05,
    "realizedLifetime": 0,
    "totalLifetime": 0.05,
    "capital": {
      "invested": 0.95,
      "investedLifetime": 0.95,
      "netFlow": -0.95,
      "netFlowLifetime": -0.95
    }
  },
  "market": {
    // market data
  }
}
```

In this example:

* The user holds **1 Yes token** currently worth **\$1.00** (`amountUsd`)
* Their cost basis is **\$0.95** (`costBasisTotal`), reflecting the buying price of the token
* No shares have been sold yet, so:
  * `realized` PnL is **\$0** and
  * `unrealized` PnL is **+\$0.05** (current value minus cost basis)
  * `total` is **+\$0.05**

<Note>
  **Unrealized PnL** is calculated using the **bid-side price** of the outcome
  token, which represents what a user would actually receive if they sold their
  position today.
</Note>

### Capital

The `capital` object is available in the [PnL API](/api-reference/positions/get-pnl-data-for-wallet-positions) and nested inside the `pnl` object in the [Positions API](/api-reference/positions/list-all-market-positions-by-wallet-address). It answers the question: **"Have I broken even yet, and how much of my own money is still at stake?"**

Unlike PnL, capital values are **price-agnostic**, which means they only change when a buy or sell event happens, not when the market moves. This makes the `capital` object a stable measure of your capital commitment to a position.

#### How it differs from PnL and Cost Basis

| Metric             | Changes on price move? | Changes on buy? | Changes on sell?    |
| ------------------ | ---------------------- | --------------- | ------------------- |
| `pnl.unrealized`   | Yes                    | Yes             | Yes                 |
| `costBasisTotal`   | No                     | Yes             | Yes (adjusted down) |
| `capital.invested` | No                     | Yes (increases) | No                  |
| `capital.netFlow`  | No                     | Yes (decreases) | Yes (increases)     |

#### Response Fields

| Field                      | Type     | Description                                                                                     |
| -------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `capital.invested`         | `number` | Sum of all buy costs for the active position. Increases with every buy, never decreases.        |
| `capital.investedLifetime` | `number` | Sum of all buy costs across all re-entries for this market.                                     |
| `capital.netFlow`          | `number` | Net capital flow for the active position: money out vs. money in. See below for interpretation. |
| `capital.netFlowLifetime`  | `number` | Net capital flow across all re-entries for this market.                                         |

#### Example Response

```json {8-13} Position with Capital Object (from PnL API) theme={null}
{
  "positionId": "dflow.prediction.KXFEDCHAIRNOM-29.6Ryen6J3RETCd4oqaViA6QsPxvxSPjLYxcPDLHa7qK19.yes.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "marketId": "dflow.prediction.KXFEDCHAIRNOM-29.6Ryen6J3RETCd4oqaViA6QsPxvxSPjLYxcPDLHa7qK19",
  "ownerAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "total": 0.05,
  "realized": 0,
  "unrealized": 0.05,
  "capital": {
    "invested": 0.95,
    "investedLifetime": 0.95,
    "netFlow": -0.95,
    "netFlowLifetime": -0.95
  },
  "realizedLifetime": 0,
  "totalLifetime": 0.05
}
```

#### Understanding netFlow

`netFlow` is calculated as **total sells minus total buys**. It tracks whether you've gotten your money back through sales.

| netFlow value | What it means                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------------- |
| Negative      | Your own capital is still locked in the position. You haven't sold enough to cover what you put in. |
| Zero          | **Breakeven.** Your initial investment has been fully returned through sells.                       |
| Positive      | You've earned back what you put in. The remaining amount is additional realized returns.            |

`netFlow` is unaffected by price changes. It only moves when you execute a trade:

* **Buy** → `netFlow` decreases (more of your capital is committed)
* **Sell** → `netFlow` increases (capital is returned to you)

#### Example

Here is a step-by-step example showing how `invested` and `netFlow` evolve across multiple trades, assuming an initial buy of \$100:

| Event          | invested | netFlow | Interpretation                                       |
| -------------- | -------- | ------- | ---------------------------------------------------- |
| Buy \$100      | \$100    | -\$100  | All capital locked in position                       |
| Buy \$100 more | \$200    | -\$200  | More capital committed (DCA)                         |
| Sell for \$75  | \$200    | -\$125  | Still \$125 of own capital in position               |
| Sell for \$125 | \$200    | \$0     | **Breakeven** — initial investment fully regained    |
| Sell for \$50  | \$200    | +\$50   | \$50 above initial investment — pure realized profit |

Note that `invested` only increases with buys, regardless of how much was sold. It represents the cumulative capital committed to the position, not the current exposure.

Use `capital.netFlow` to show users how far they are from breakeven. A value of 0 means they've gotten their money back through sells. Anything above 0 is pure **realized** profit.

## Protocol-Specific Additional Data

The `additionalData` field contains DFlow-specific metadata that may be useful for advanced integrations:

```json DFlow Additional Data theme={null}
{
  "additionalData": {
    "ticker": "CONTROLH-2026-R",
    "eventTicker": "CONTROLH-2026",
    "marketLedger": "G7EqT9zdoRKt5RScDhpKjryEnT2SVjAViBJb34smb6SH",
    "purchaseToken": {
      "icon": "https://...",
      "symbol": "USDC",
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "decimals": 6
    },
    "redemptionStatus": "pending"
  }
}
```

| Field              | Description                                                                             |
| ------------------ | --------------------------------------------------------------------------------------- |
| `ticker`           | Kalshi's / DFlow's specific market identifier (e.g., "CONTROLH-2026-R" for Republicans) |
| `eventTicker`      | Event-level identifier — all markets in the same event share this ticker                |
| `marketLedger`     | On-chain address of the market ledger that handles positions and redemptions            |
| `purchaseToken`    | The token used to purchase outcome tokens (USDC or CASH)                                |
| `redemptionStatus` | Current redemption state: `open` or `pending`                                           |

<Note>
  The `eventTicker` in `additionalData` corresponds conceptually to the
  `bundleId` field. Both can be used to identify markets that belong together.
</Note>

## Take action in a market

We are currently not supporting Blinks for prediction markets. If you want to request this feature, please reach out to us at [hello@dialect.to](mailto:hello@dialect.to).

If you still want to support actions, please checkout [DFlow's documentation](https://pond.dflow.net/build/prediction-markets/).


# Yield Markets
Source: https://docs.dialect.to/markets/market-types/yield

Get Solana's top yield markets with real-time data and ready-to-use Blinks for seamless DeFi interactions.

<img alt="Yield Market Details" />

Yield markets allow users to deposit assets and earn returns through various DeFi strategies. Unlike traditional lending markets where returns come from borrower interest, yield markets generate returns through liquidity provision, staking rewards, automated strategies, and protocol-specific incentives.

Our Markets API already contains lots of information that you would manually collect via multiple API calls throughout protocols and providers, such as:

* basic protocol information (one call contains multiple protocols),
* APY information,
* token information,
* vault information,
* actions, etc.

By enriching the response with all of this information, it makes the API powerful enough to drive full-fledged dashboards and applications as well as smaller widgets, cards or notifications - All in a single API call!

## Supported Protocols

Our Markets API provides unified access to yield markets across multiple protocols:

* [**Kamino Lend**](https://kamino.com/lend)
* [**Lulo**](https://lulo.fi/)
* [**Jupiter Earn**](https://jup.ag/lend/earn)
* [**DeFiTuna Lend**](https://defituna.com/lend)
* [**DeFiCarrot**](https://deficarrot.com/)

If you want more information on the protocols that are supported, please refer to the [Supported Protocols Section](/markets/supported-protocols) page.

### Yield vs Lending

Yield markets and lending markets have different mechanics. Below is a side-by-side comparison:

| Feature               | Yield Markets                              | Lending Markets                                          |
| --------------------- | ------------------------------------------ | -------------------------------------------------------- |
| **Primary Action**    | Deposit to earn                            | Deposit to lend, with borrowing option                   |
| **Return Source**     | Earnings collected through DeFi strategies | Borrower interest payments + protocol rewards (optional) |
| **Collateralization** | Not required                               | Required for borrowing                                   |
| **Risk Profile**      | Strategy-dependent                         | Credit risk + liquidation risk (if assets were borrowed) |
| **Composability**     | Mostly single-sided                        | Two-sided (lend + borrow)                                |

## Data Structure

Below is an example of a yield market response from the Markets API. Based on customer demand, we may add more fields to the response in the future.

For the latest data structure, please have a look at our [Markets API Reference](/api-reference/markets/list-all-markets) page.

<Note>
  Please note that we do our best to design our APIs to be non-breaking. It is
  recommended to filter the response and only include the fields / types you
  need to ensure it won't break your application if new fields are added over
  time.
</Note>

```json Yield Markets Data Structure theme={null}
{
  "id": "string",                    // Unique market identifier
  "type": "yield",                   // Market type
  "provider": {
    "id": "string",                  // Protocol identifier
    "name": "string",                // Protocol display name
    "icon": "string"                 // Protocol icon URL
  },
  "token": {
    "address": "string",             // Token mint address
    "symbol": "string",              // Token symbol
    "decimals": number,              // Token decimals
    "icon": "string"                 // Token icon URL
  },
  "websiteUrl": "string",            // Direct link to protocol (optional)
  "depositApy": number,              // Total APY including rewards
  "baseDepositApy": number,          // Base APY without rewards
  "baseDepositApy30d": number,       // Historical 30-day average (optional)
  "baseDepositApy90d": number,       // Historical 90-day average (optional)
  "baseDepositApy180d": number,      // Historical 180-day average (optional)
  "totalDeposit": number,            // Total deposited (token amount)
  "totalDepositUsd": number,         // Total deposited (USD value)
  "rewards": [                       // Additional reward tokens (optional)
    {
      "type": "deposit",
      "apy": number,
      "token": {
        "address": "string",
        "symbol": "string",
        "decimals": number,
        "icon": "string"
      },
      "marketAction": "deposit"
    }
  ],
  "additionalData": {},               // Protocol-specific metadata (varies by market)
  "actions": {
    "deposit": {
      "blinkUrl": "string"           // Blink action URL
    },
    "withdraw": {
      "blinkUrl": "string"           // Blink action URL
    }
    // Additional actions may be available (e.g., claimRewards)
  }
}
```

## Practical Example

In order to better understand how the API works, let's walk through an example response for the Kamino Lend USDC Prime Vault below:

```json API Response for Kamino Lend USDC Prime Vault theme={null}
{
  "id": "kamino.lend.HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E",
  "type": "yield",
  "provider": {
    "id": "kamino",
    "name": "Kamino",
    "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/5cddfb2e-c98e-4734-528b-b541fb5e2b00/public"
  },
  "token": {
    "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "symbol": "USDC",
    "decimals": 6,
    "icon": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/logo.png"
  },
  "websiteUrl": "https://kamino.com/lend/usdc-prime",
  "depositApy": 0.0389,
  "baseDepositApy": 0.0216,
  "baseDepositApy30d": 0.0618,
  "baseDepositApy90d": 0.0824,
  "baseDepositApy180d": 0.1184,
  "totalDeposit": 174644281.764,
  "totalDepositUsd": 174588566.75,
  "rewards": [
    {
      "type": "deposit",
      "apy": 0.0173,
      "token": {
        "address": "KMNo3nJsBXfcpJTVhZcXLW7RmTwTt4GVFE7suUBo9sS",
        "symbol": "KMNO",
        "decimals": 6,
        "icon": "https://cdn.kamino.finance/kamino.svg"
      },
      "marketAction": "deposit"
    }
  ],
  "additionalData": {
    "vaultAddress": "HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E",
    "vaultSlug": "usdc-prime",
    "vaultName": "USDC Prime",
    "vaultRiskProfile": "Conservative"
  },
  "actions": {
    "deposit": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/usdc-prime/deposit"
    },
    "withdraw": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/usdc-prime/withdraw"
    },
    "claimRewards": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/usdc-prime/claim-rewards"
    }
  }
}
```

### Understanding the Response

What you can see here is the original response from the API. As mentioned in the introduction section, this response is powerful enough to drive full-fledged dashboards and applications.

Let's break it down into its components:

* **Market Identity:**

  * `id`: Unique identifier combining protocol, market type, and address
  * `type`: Market category (always `yield` for yield markets)
  * `provider`: Protocol information for branding in your UI
  * `token`: Full token information including address, symbol, decimals and icon
  * `websiteUrl`: Direct link to the market on the protocol's website

* **APY Breakdown:**

  * `depositApy` (3.89%) — Total combined yield including rewards
  * `baseDepositApy` (2.16%) — Core yield from the strategy
  * `baseDepositApy30d` (6.18%) — Historical 30-day average
  * `baseDepositApy90d` (8.24%) — Historical 90-day average
  * `baseDepositApy180d` (11.84%) — Historical 180-day average
  * `rewards` array (1.73% KMNO) — Additional incentive tokens for depositors

* **Market Metrics:**

  * This vault holds \$174.6M USDC across all depositors (`totalDeposit` and `totalDepositUsd`).

  **Note:** `totalDeposit` is in the token's native units, while the
  `totalDepositUsd` is in USD.

* **Actions:** The `actions` object contains Blink URLs for `deposit`, `withdraw`, and optionally `claimRewards` depending on the protocol.

* **Additional Data:** The `additionalData` object contains protocol-specific metadata. In this example, we have the following additional data for the Kamino Lend USDC Prime Vault:
  * `vaultAddress`: The address of the vault
  * `vaultSlug`: The slug of the vault
  * `vaultName`: The name of the vault
  * `vaultRiskProfile`: The risk profile of the vault

### Protocol-Specific Additional Data

The `additionalData` field varies by provider. In our example, we have the following additional data for the Kamino Lend USDC Prime Vault:

```json Kamino Lend theme={null}
{
  "additionalData": {
    "vaultAddress": "HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E",
    "vaultSlug": "usdc-prime",
    "vaultName": "USDC Prime",
    "vaultRiskProfile": "Conservative"
  }
}
```

If you will look into Jupiter Earn or DeFi Carrot, you will see that they will return `shareToken` additional data, which is the token information of the token that you will receive when you deposit in return for your deposit.

```json Jupiter Earn and DeFi Carrot theme={null}
{
  "additionalData": {
    "shareToken": {
      "address": "CRTx1JouZhzSU6XytsE42UQraoGqiHgxabocVfARTy2s",
      "symbol": "CRT",
      "decimals": 9,
      "icon": "https://res.cloudinary.com/dnu9h68sh/image/upload/v1757607855/carrot_rf3gkd.png",
      "name": "CRT"
    }
  }
}
```

and Lulo will return the `withdrawCooldownHours` additional data:

```json Lulo Boosted theme={null}
{
  "additionalData": {
    "withdrawCooldownHours": 24
  }
}
```

As we continue to add more providers and markets, the `additionalData` field will continue to grow and be more powerful. If you need more information or want to check out what protocols are supported, please refer to the [Supported Protocols](/markets/supported-protocols) page.


# Using Markets and Blinks
Source: https://docs.dialect.to/markets/quick-start

Learn how to go from market data to ready-to-sign blockchain transactions using blinks

The Markets and Positions APIs provide a strong read layer for Solana's top DeFi protocols. Using them allows you to build sophisticated applications for your users as well as AI agents. But reading is just one part of the equation.

Writing to the blockchain is just as important. Blockchain links (Blinks) fill this gap by providing ready-to-sign transactions for each available protocol, so that your users can take immediate action based on the data they see.

This guide walks you through the full process of fetching market data, understanding the response structure, and executing transactions.

## What You'll Learn

By the end of this guide, you'll understand how to:

* Fetch real-time market data from multiple protocols
* Identify available actions in the API response
* Use Blinks to execute transactions
* Track positions across protocols

## Getting Real-Time Market Data

The [Markets API](/api-reference/markets/list-all-markets) aggregates real-time market data from [multiple protocols](/markets/supported-protocols) and returns it in a detailed, unified data format.

### Fetching Market Data

In our example, we will focus on data from the Kamino lending market. You can find the full API reference for the Markets API [here](/api-reference/markets/list-all-markets).

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch(
    'https://markets.dial.to/api/v0/markets?type=yield&provider=kamino',
    {
      headers: {
        'x-dialect-client-key': 'pk_demo'
      }
    }
  );

  const data = await response.json();
  console.log(data.markets);
  ```

  ```bash cURL theme={null}
  curl 'https://markets.dial.to/api/v0/markets?type=yield&provider=kamino' \
    --header 'x-dialect-client-key: pk_demo'
  ```
</CodeGroup>

<Tip>
  The `pk_demo` key is for testing purposes only. [Request your own client key](/markets/api-keys) for production use.
</Tip>

### Understanding Market Data

The API returns detailed market information including rates, liquidity, rewards, and available actions. You can see the full response for this market in the accordion below.

<Accordion title="View Complete Response Example">
  ```json theme={null}
  {
    "markets": [
      {
        "id": "kamino.lend.BqBsS4myH82S4yfqeKjXSF7yErWwSi5WTshSzKmHQgzw",
        "type": "yield",
        "provider": {
          "id": "kamino",
          "name": "Kamino",
          "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/5cddfb2e-c98e-4734-528b-b541fb5e2b00/public"
        },
        "token": {
          "address": "2u1tszSeqZ3qBWF3uNGPFc8TzMk2tdiwknnRMWGWjGWH",
          "symbol": "USDG",
          "decimals": 6,
          "icon": "https://424565.fs1.hubspotusercontent-na1.net/hubfs/424565/GDN-USDG-Token-512x512.png"
        },
        "websiteUrl": "https://kamino.com/lend/usdg-prime",
        "depositApy": 0.1273,
        "baseDepositApy": 0.0997,
        "baseDepositApy30d": 0.0818,
        "baseDepositApy90d": 0.1678,
        "baseDepositApy180d": 0.1993,
        "totalDeposit": 17454683.181014914,
        "totalDepositUsd": 17454683.18,
        "rewards": [
          {
            "type": "deposit",
            "apy": 0.0276,
            "token": {
              "address": "KMNo3nJsBXfcpJTVhZcXLW7RmTwTt4GVFE7suUBo9sS",
              "symbol": "KMNO",
              "decimals": 6,
              "icon": "https://cdn.kamino.finance/kamino.svg"
            },
            "marketAction": "deposit"
          }
        ],
        "additionalData": {
          "vaultAddress": "BqBsS4myH82S4yfqeKjXSF7yErWwSi5WTshSzKmHQgzw",
          "vaultSlug": "usdg-prime"
        },
        "actions": {
          "deposit": {
            "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/usdg-prime/deposit"
          },
          "withdraw": {
            "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/usdg-prime/withdraw"
          }
        }
      },
      // ... more markets ...
    ]
  }
  ```
</Accordion>

To beter understand the response, let's break it down into its components.

#### Market Identity

Each market is uniquely identified by its protocol, type, and token:

```json theme={null}
{
  "id": "kamino.lend.BqBsS4myH82S4yfqeKjXSF7yErWwSi5WTshSzKmHQgzw",
  "type": "yield",
  "provider": {
    "id": "kamino",
    "name": "Kamino",
    "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/5cddfb2e-c98e-4734-528b-b541fb5e2b00/public"
  },
  "token": {
    "address": "2u1tszSeqZ3qBWF3uNGPFc8TzMk2tdiwknnRMWGWjGWH",
    "symbol": "USDG",
    "decimals": 6,
    "icon": "https://424565.fs1.hubspotusercontent-na1.net/hubfs/424565/GDN-USDG-Token-512x512.png"
  },
  "websiteUrl": "https://kamino.com/lend/usdg-prime"
}
```

* **`id`**: Unique identifier combining protocol, market type, and address
* **`type`**: Market category, e.g. `yield` for lend, `lending` for borrow etc.
* **`provider`**: Protocol information for branding in your UI
* **`token`**: Token information for use in your application
* **`websiteUrl`**: Direct link to the market on the protocol's website

#### Understanding Earnings

The earnings structure shows the current and historical market rates including rewards.

```json theme={null}
{
  "depositApy": 0.1273,              // 12.73% total
  "baseDepositApy": 0.0997,          // 9.97% base rate
  "baseDepositApy30d": 0.0818,       // 30-day average
  "baseDepositApy90d": 0.1678,       // 90-day average
  "baseDepositApy180d": 0.1993,      // 180-day average
  "rewards": [
    {
      "type": "deposit",
      "apy": 0.0276,                 // 2.76% in KMNO tokens
      "token": {
        "symbol": "KMNO",
        "address": "KMNo3nJsBXfcpJTVhZcXLW7RmTwTt4GVFE7suUBo9sS"
      }
    }
  ]
}
```

* **`depositApy`**: Total yield you earn (base rate + all rewards combined)
* **`baseDepositApy`**: The protocol's base lending rate
* **`baseDepositApy30d/90d/180d`**: Historical APY averages over different time periods
* **`rewards`**: Additional earnings from rewards on top of the base rate

In this example: 9.97% (base) + 2.76% (KMNO rewards) = 12.73% (total APY)

<Tip>
  Markets can offer multiple reward tokens. See the [Rewards Guide](/markets/rewards) for detailed examples.
</Tip>

#### Market Liquidity

Market size indicators help you understand liquidity and stability:

```json theme={null}
{
  "totalDeposit": 17454683.181014914,
  "totalDepositUsd": 17454683.18
}
```

* **`totalDeposit`**: Total tokens deposited (in token's native units)
* **`totalDepositUsd`**: Total value in USD

#### Available Actions

Each market includes a set of actions that can be executed on the market. A more detailed explanation of the actions is provided in the next section.

```json theme={null}
{
  "actions": {
    "deposit": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/usdg-prime/deposit"
    },
    "withdraw": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/usdg-prime/withdraw"
    }
  }
}
```

#### Additional Data

Based on the market, this field can be empty or contain protocol-specific data:

```json theme={null}
{
  "additionalData": {
    "vaultAddress": "BqBsS4myH82S4yfqeKjXSF7yErWwSi5WTshSzKmHQgzw",
    "vaultSlug": "usdg-prime"
  }
}
```

## Taking Action on a Market

The `actions` object contains blink URLs for each available operation. These URLs return ready-to-sign transactions, which eliminates the need for teams to integrate protocols through complex SDKs as well as the maintenance of these integrations.

### From Markets to Transactions

Once you have a blink URL from the Markets API, you can use it to fetch and execute transactions. The process involves three steps:

<Steps>
  <Step title="Fetch transaction">
    Send a `POST` request with user's wallet address and the required parameters to receive a transaction from the API
  </Step>

  <Step title="Update blockhash (recommended)">
    It's recommended to update the blockhash of the transaction before signing it to ensure it remains valid
  </Step>

  <Step title="Sign and send transaction">
    Sign the transaction with any Solana wallet and broadcast it to the network
  </Step>
</Steps>

### Integration Options

There are two ways to integrate blinks into your application. Please follow the links below for hands-on code examples:

<CardGroup>
  <Card title="Programmatic (Headless)" icon="code" href="/standard-blinks-library/quick-start">
    Full control over the user experience. Ideal for custom UIs and AI agents.
  </Card>

  <Card title="UI Components" icon="puzzle-piece" href="/blinks/blinks-client/integrate/ui-components/blinks">
    Drop-in components with automatic rendering and state management of blinks.
  </Card>
</CardGroup>

## Tracking Positions Across Protocols

After executing transactions, track user positions across all protocols:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch(
    'https://markets.dial.to/api/v0/positions/owners?walletAddresses=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176',
    {
      headers: {
        'x-dialect-client-key': 'pk_demo'
      }
    }
  );

  const data = await response.json();
  console.log(data.positions);
  ```

  ```bash cURL theme={null}
  curl 'https://markets.dial.to/api/v0/positions/owners?walletAddresses=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176' \
    --header 'x-dialect-client-key: pk_demo'
  ```
</CodeGroup>

<Tip>
  The `pk_demo` key is for testing purposes only. [Request your own client key](/markets/api-keys) for production use.
</Tip>

Position data includes:

* Current balance and USD value
* Accumulated yield
* Health factor for leveraged positions
* Available actions
* etc.

As of today we offer two endpoints that would allow you to track positions across protocols:

<CardGroup>
  <Card title="List Positions by Wallet" icon="wallet" href="/api-reference/positions/list-all-market-positions-by-wallet-address">
    Get all positions for a wallet address across supported protocols
  </Card>

  <Card title="Historical Position Data" icon="chart-line" href="/api-reference/positions/get-historical-position-snapshots">
    Track position growth and portfolio analytics over time
  </Card>
</CardGroup>

For more information about how to use the historical position data endpoint, please see the [Historical Position Data](/markets/history) guide.


# Understanding Rewards
Source: https://docs.dialect.to/markets/rewards

Learn how reward systems work across different DeFi protocols and how to interpret rewards data in both the Markets API and Positions API.

Rewards are additional incentives provided by DeFi protocols to encourage specific actions like depositing, borrowing, or maintaining certain positions. Unlike base APY rates generated by protocol activity, rewards are typically funded by the protocol itself or partners to drive liquidity and usage.

## Markets API Rewards

### Understanding APY Structure

The Markets API provides three types of APY data for each market:

#### Base APY (Natural Protocol Yields)

This is the APY you'll always get. It's excluding the [rewards](#rewards-extra-incentives).

* **`baseDepositApy`** - Interest earned from borrowers paying to use your deposited assets
* **`baseBorrowApy`** - Interest rate you pay to borrow assets from the protocol

```json theme={null}
{
  "baseDepositApy": 0.0345,
  "baseBorrowApy": 0.1375
}
```

#### Rewards (Extra Incentives)

This is the APY that comes on top of the base APY for doing a specific actions on the platform. These are funded by protocols/partners to drive specific behaviors.

* **`rewards` array** - Additional token incentives on top of base yields

```json theme={null}
{
  "rewards": [
    {
      "type": "deposit",
      "apy": 0.0846,
      "token": {
        "address": "AuQaustGiaqxRvj2gtCdrd22PBzTn8kM3kEPEkZCtuDw",
        "symbol": "ADX",
        "decimals": 6,
        "icon": "https://i.ibb.co/52cM38T/adrena-logo-adx-color-200x200.png"
      },
      "marketAction": "deposit"
    }
  ]
}
```

#### Total APY (What You Actually Earn)

This is the APY including rewards.

* **`depositApy`** = `baseDepositApy` + sum of all deposit reward APYs
* **`borrowApy`** = `baseBorrowApy` - sum of all borrow reward APYs (rewards reduce cost for borrowers)

```json theme={null}
{
  "depositApy": 0.1041,
  "borrowApy": 0.0459
}
```

### Example: Real Market Analysis

Let's walk through actual market data from Kamino to understand how rewards work:

#### Deposit Rewards

Deposit rewards increase the yield of depositing an asset. You can earn either a single reward token or multiple tokens from one deposit action.

##### **Single Token Reward**

This example shows a market with a single token reward for depositing USDC, in this case ADX tokens.

```json theme={null}
{
  "id": "kamino.5bgPMvzZv29jkFEuMwxQRJQf64gKcPfLEEUHhyrP8tce",
  "token": {
    "symbol": "USDC",
    "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "decimals": 6,
    "icon": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/logo.png"
  },
  "baseDepositApy": 0.032, // 3.2% from lending activity
  "depositApy": 0.1041, // 10.41% total (base + rewards)
  "baseBorrowApy": 0.1363, // 13.63% borrow cost
  "borrowApy": 0.1363, // Same - no borrow rewards
  "rewards": [
    {
      "type": "deposit", // Single action needed
      "apy": 0.0721, // 7.21% in ADX tokens
      "token": {
        "address": "AuQaustGiaqxRvj2gtCdrd22PBzTn8kM3kEPEkZCtuDw",
        "symbol": "ADX",
        "decimals": 6,
        "icon": "https://i.ibb.co/52cM38T/adrena-logo-adx-color-200x200.png"
      },
      "marketAction": "deposit" // You deposit USDC
    }
  ]
}
```

**What This Tells You:**

* **Depositors earn:** 3.2% base + 7.21% ADX rewards = **10.41% total**
* **Borrowers pay:** 13.63% (no rewards to reduce cost)
* **Action needed:** Deposit USDC to get ADX rewards

##### **Multiple Token Rewards**

Some markets offer multiple reward tokens for a single deposit action. Here's a real example where depositing USDS earns both HUMA and USDS rewards:

```json theme={null}
{
  "id": "kamino.9XbExNmevn7jzNzbX3kAzxKq83mdYP5ZN4xcYpLUVHGU",
  "token": {
    "symbol": "USDS",
    "address": "USDSwr9ApdHk5bvJKMjzff41FfuX8bSxdKcR81vTwcA",
    "decimals": 6,
    "icon": "https://ipfs.io/ipfs/QmTW9HWfb2wsQqEVJiixkQ73Nsfp2Rx4ESaDSiQ7ThwnFM"
  },
  "depositApy": 0.1171, // 11.71% total return
  "baseDepositApy": 0.0079, // 0.79% base lending yield
  "borrowApy": 0.0199, // 1.99% borrow cost
  "baseBorrowApy": 0.0199, // Same - no borrow rewards
  "rewards": [
    {
      "type": "deposit",
      "apy": 0.0553, // 5.53% in HUMA tokens
      "token": {
        "address": "HUMA1821qVDKta3u2ovmfDQeW2fSQouSKE8fkF44wvGw",
        "symbol": "HUMA",
        "decimals": 6,
        "icon": "https://meta.huma.finance/huma.svg"
      },
      "marketAction": "deposit"
    },
    {
      "type": "deposit",
      "apy": 0.054, // 5.4% in USDS tokens
      "token": {
        "address": "USDSwr9ApdHk5bvJKMjzff41FfuX8bSxdKcR81vTwcA",
        "symbol": "USDS",
        "decimals": 6,
        "icon": "https://ipfs.io/ipfs/QmTW9HWfb2wsQqEVJiixkQ73Nsfp2Rx4ESaDSiQ7ThwnFM"
      },
      "marketAction": "deposit"
    }
  ]
}
```

**What This Tells You:**

* **Depositors earn:** 0.79% base + 5.53% HUMA + 5.4% USDS = **11.71% total**
* **Borrowers pay:** 1.99% (no rewards)
* **Action needed:** Just deposit USDS once to earn both HUMA and USDS rewards
* **Calculation:** `depositApy` (11.71%) = `baseDepositApy` (0.79%) + HUMA APY (5.53%) + USDS APY (5.4%)

<Note>
  Multiple token rewards are also possible for borrow rewards. The same rules
  apply as for deposit rewards.
</Note>

#### Borrow Rewards

Borrow rewards reduce the cost of borrowing an asset.

```json theme={null}
{
  "id": "kamino.FBLWZjz7nKJUUMBah7Gzv3GqWEpzZdhwJy79YS8tZUg1",
  "token": {
    "symbol": "jitoSOL",
    "address": "J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn",
    "decimals": 9,
    "icon": "https://storage.googleapis.com/token-metadata/JitoSOL-256.png"
  },
  "baseDepositApy": 0.0739, // 7.39% natural staking yield
  "depositApy": 0.0739, // Same - no deposit rewards
  "baseBorrowApy": 0.0918, // 9.18% natural borrow cost
  "borrowApy": 0.032, // 3.2% actual cost (reduced by rewards)
  "rewards": [
    {
      "type": "borrow", // Single action needed
      "apy": 0.0598, // 5.98% in JTO tokens
      "token": {
        "address": "jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL",
        "symbol": "JTO",
        "decimals": 9,
        "icon": "https://metadata.jito.network/token/jto/image"
      },
      "marketAction": "borrow" // You borrow jitoSOL
    }
  ]
}
```

**What This Tells You:**

* **Depositors earn:** 7.39% (just the base staking yield, no extra rewards)
* **Borrowers earn:** 9.18% borrow cost - 5.98% JTO rewards = **3.2% net cost**
* **Action needed:** Borrow jitoSOL to get JTO rewards

#### Markets with Both Deposit and Borrow Rewards

Some markets incentivize both sides: depositors AND borrowers in the same market. Here's a real SOL market example:

```json theme={null}
{
  "id": "kamino.4oigbthMAgjTMPyw8dBxhxU59YMtvNDHqhpR3W4HAzBM",
  "token": {
    "symbol": "SOL",
    "address": "So11111111111111111111111111111111111111112",
    "decimals": 9,
    "icon": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png"
  },
  "depositApy": 0.0695, // 6.95% total deposit return
  "baseDepositApy": 0.0596, // 5.96% natural lending yield
  "borrowApy": 0.0665, // 6.65% actual borrow cost
  "baseBorrowApy": 0.0696, // 6.96% natural borrow cost
  "rewards": [
    {
      "type": "deposit",
      "apy": 0.0098, // 0.98% BLZE for depositors
      "token": {
        "address": "BLZEEuZUBVqFhj8adcCFPJvPVCiCyVmh3hkJMrU8KuJA",
        "symbol": "BLZE",
        "decimals": 9,
        "icon": "https://solblaze.org/assets/blze.png?v=2"
      },
      "marketAction": "deposit"
    },
    {
      "type": "borrow",
      "apy": 0.0031, // 0.31% BLZE for borrowers
      "token": {
        "address": "BLZEEuZUBVqFhj8adcCFPJvPVCiCyVmh3hkJMrU8KuJA",
        "symbol": "BLZE",
        "decimals": 9,
        "icon": "https://solblaze.org/assets/blze.png?v=2"
      },
      "marketAction": "borrow"
    }
  ]
}
```

**What This Tells You:**

* **Depositors earn:** 5.96% base + 0.98% BLZE = **6.95% total**
* **Borrowers pay:** 6.96% base - 0.31% BLZE = **6.65% net cost**
* **Both sides win:** Depositors get higher yields, borrowers get lower costs
* **Same reward token:** Both depositors and borrowers earn BLZE tokens

### Reading Reward Data

| Field          | What it tells you                                                        |
| -------------- | ------------------------------------------------------------------------ |
| `type`         | **Reward type**: either `"deposit"` or `"borrow"`                        |
| `apy`          | **Annual percentage yield** for this reward token                        |
| `token`        | **Token details**: address, symbol, decimals, icon                       |
| `marketAction` | **Your action in the market to earn this reward**: mostly matches `type` |

### Claiming Rewards

Most protocols allow you to claim accumulated rewards at any time. Look for the `claimRewards` action in the market data:

```json {9-11} theme={null}
{
  "actions": {
    "deposit": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lending/..."
    },
    "withdraw": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lending/..."
    },
    "claimRewards": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lending/..."
    }
  }
}
```

## Positions API Rewards

The Positions API shows you the rewards **you** have already earned in **your** positions. Unlike the Markets API, which provides static information about available reward opportunities, the Positions API is wallet-specific, which means that you provide your wallet address and get back your actual accrued rewards.

### What the Positions API Shows

When you query the Positions API with your wallet address, you get:

1. **Your actual accrued rewards** - The real amounts of reward tokens you've earned. Even if you've withdrawn from a position, your rewards remain visible
2. **Nested market data** - Current market information (including the reward rules from the Markets API) for convenience, so you don't need a separate API call
3. **Open positions** - The open positions you have in the market incl. market data, etc.

### The "reward" Position Type (recommended)

When calling our Positions API, you will receive active positions, e.g. positions with the type `yield` or `lending` and positions with the type `reward` that reflects the rewards you have earned from those positions.

The `reward` position type is an atomic tracking system that ensures your rewards are always visible, even after the main position was closed, which is why it's recommended to use this type over the deprecated `rewards` array.

**The Problem with the `rewards` array:**

* The `rewards` array is part of **active** positions
* When you close a position (withdraw everything), the position amount becomes 0 and it no longer appears in the positions array
* But you might still have unclaimed rewards from that position (for example, Kamino season rewards that aren't available to claim yet)
* Without the position in the array, those rewards would disappear from your view

**The Solution with the `reward` position type:**

The `reward` position type ensures that each reward is tracked separately, bringing you the following benefits:

* Your rewards are always visible, even after the main position is closed
* You never lose track of rewards you're entitled to claim
* The system maintains a clear record of all your reward entitlements
* Nested data structure allows you to easily access the parent position and the reward token details

#### Example Reward Position

Here's a complete reward position example for a Kamino Allez USDC yield position. Please note that we might add more fields to the reward position in the future, so please check the [API Reference](/api-reference/positions/list-all-market-positions-by-wallet-address) for the latest details.

```json Reward Position Example Kamino Lend theme={null}
{
  "id": "kamino.reward.2ArD5N7CBi9JHxQwPWkvUFVLbowBA4nAcDRYGDwfmhpD.FAFxVxnkzZHMCodkWyoccgUNgVScqMw2mhhQBYDFjFAF.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "type": "reward",
  "ownerAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "bundleId": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo",
  "token": {
    "address": "FAFxVxnkzZHMCodkWyoccgUNgVScqMw2mhhQBYDFjFAF",
    "symbol": "FAF",
    "decimals": 6,
    "icon": "https://arweave.net/kOySlhk3gkg16EZrt9WssPQW4vv1P36I51c3OX3lmEc"
  },
  "marketId": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo",
  "position": {
    "id": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
    "type": "yield"
  },
  "additionalData": {},
  "amount": 0.000398,
  "market": {
    "id": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo",
    "type": "yield",
    "provider": {
      "id": "kamino",
      "name": "Kamino",
      "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/5cddfb2e-c98e-4734-528b-b541fb5e2b00/public"
    },
    "token": {
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "decimals": 6,
      "icon": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/logo.png"
    },
    "websiteUrl": "https://kamino.com/lend/allez-usdc",
    "depositApy": 0.0539,
    "baseDepositApy": 0.0315,
    "baseDepositApy30d": 0.0733,
    "baseDepositApy90d": 0.0942,
    "baseDepositApy180d": 0.1225,
    "totalDeposit": 34280362.60412186,
    "totalDepositUsd": 34273898.7,
    "rewards": [
      // Public data from Markets API,
      // displaying the potential rewards for the market,
      // not the user's actual rewards (good to use)
      {
        "type": "deposit",
        "apy": 0.0002,
        "token": {
          "address": "HUMA1821qVDKta3u2ovmfDQeW2fSQouSKE8fkF44wvGw",
          "symbol": "HUMA",
          "decimals": 6,
          "icon": "https://meta.huma.finance/huma.svg"
        },
        "marketAction": "deposit"
      },
      {
        "type": "deposit",
        "apy": 0.0223,
        "token": {
          "address": "KMNo3nJsBXfcpJTVhZcXLW7RmTwTt4GVFE7suUBo9sS",
          "symbol": "KMNO",
          "decimals": 6,
          "icon": "https://cdn.kamino.finance/kamino.svg"
        },
        "marketAction": "deposit"
      }
    ],
    "additionalData": {
      "vaultAddress": "A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo",
      "vaultSlug": "allez-usdc",
      "vaultName": "Allez USDC",
      "vaultRiskProfile": "Balanced"
    },
    "actions": {
      "deposit": {
        "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/allez-usdc/deposit"
      },
      "withdraw": {
        "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/allez-usdc/withdraw"
      },
      "claimRewards": {
        "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/allez-usdc/claim-rewards"
      }
    }
  }
}
```

**Field Breakdown:**

| Field       | Description                                                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `id`        | Unique identifier for the reward position containing of the protocol, product, identifier, reward token, and reward provenance |
| `type`      | Always `"reward"` for reward positions                                                                                         |
| `token`     | The reward token you've earned (e.g., KMNO, JTO, HUMA, FAF)                                                                    |
| `amount`    | Quantity of reward tokens accrued                                                                                              |
| `amountUsd` | USD value of your rewards (optional)                                                                                           |
| `marketId`  | Which market generated this reward                                                                                             |
| `position`  | Reference to the parent position (type and id) that generated this reward                                                      |
| `market`    | Full nested market data including current APYs, available rewards, and claim actions                                           |

#### Accessing Reward Positions

To work with reward positions in your code, filter the positions array by type:

```typescript theme={null}
// Get all reward positions from the Positions API response
const rewardPositions = positions.filter((p) => p.type === "reward");

// Example: Display all rewards
rewardPositions.forEach((reward) => {
  console.log(`${reward.amount} ${reward.token.symbol}`);
  // soon: we will add the amountUsd field to the reward position
  if (reward.amountUsd) {
    console.log(`  Worth: $${reward.amount.toFixed(2)}`);
  }
});
```

#### Linking to Parent Positions

Each reward position includes a `position` field that references the parent position that generated it:

```typescript theme={null}
// Find the parent position for a reward
const reward = rewardPositions[0];
const parentPosition = positions.find((p) => p.id === reward.position.id);

if (parentPosition) {
  console.log(`This ${reward.token.symbol} reward came from:`);
  console.log(`  Position type: ${reward.position.type}`);
  console.log(`  Position amount: ${parentPosition.amount}`);
} else {
  console.log(`Parent position closed, but reward remains claimable`);
}
```

This is particularly useful when the parent position has been closed (withdrawn), but the rewards are still available to claim.

### Nested Market Data

For your convenience, each position in the Positions API includes the current market data. This means you can display everything you need without making a separate call to the Markets API.

The nested `market` object includes:

* Current APY rates (`depositApy`, `borrowApy`, `baseDepositApy`, `baseBorrowApy`)
* Available rewards (the Markets API `rewards` array with APY and token info)
* Market details (token info, provider, website URL)
* Market actions (deposit, withdraw, borrow, repay Blink URLs)

### The `rewards` Array (deprecated)

<Warning>
  This array is deprecated and will be removed in the future. Please migrate to
  using the [`reward` position
  type](/markets/rewards#the-“reward”-position-type-recommended) instead, which
  provides the same data with better reliability and additional features.
</Warning>

The old way of tracking rewards was through a `rewards` array within the `lending` and `yield` type positions:

```json Reward Position Example Kamino Lend theme={null}
{
  "id": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "type": "yield",
  "marketId": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo",
  "ownerAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "bundleId": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo",
  "rewards": [
    {
      "tokenAddress": "FAFxVxnkzZHMCodkWyoccgUNgVScqMw2mhhQBYDFjFAF",
      "amount": 0.000398
    },
    {
      "tokenAddress": "HUMA1821qVDKta3u2ovmfDQeW2fSQouSKE8fkF44wvGw",
      "amount": 0.002389
    },
    {
      "tokenAddress": "KMNo3nJsBXfcpJTVhZcXLW7RmTwTt4GVFE7suUBo9sS",
      "amount": 0.04918834980802605
    },
    {
      "tokenAddress": "KMNo3nJsBXfcpJTVhZcXLW7RmTwTt4GVFE7suUBo9sS",
      "amount": 0.26065915278827795
    }
  ],
  "additionalData": {},
  "amount": 2.013886,
  "amountUsd": 2.01,
  "market": {
    // more market data here
  }
  // more data here (ltv, actions, etc.)
}
```

**Why This Is Deprecated:**

The `rewards` array has a critical limitation: when you close a position (withdraw all funds), the position disappears from the array, and so do your unclaimed rewards. This is problematic because:

* Some protocols have delayed reward claiming (e.g., seasonal rewards)
* You could lose track of rewards you're entitled to claim
* No way to see historical rewards from closed positions

**Migration to Reward Position Type:**

Instead of using the `rewards` array, use the new `reward` position type which solves these problems:

```typescript theme={null}
// ❌ Old way (deprecated) - rewards disappear when position closes
const oldRewards = positions
  .filter((p) => p.type === "yield" || p.type === "lending")
  .flatMap((p) => p.rewards || []);

// ✅ New way (recommended) - rewards persist even after position closes
const newRewards = positions.filter((p) => p.type === "reward");
```

**Comparison:**

| Aspect               | Deprecated `rewards` Array  | New `reward` Position Type                        |
| -------------------- | --------------------------- | ------------------------------------------------- |
| **Availability**     | Only on active positions    | Always visible, even after position closes        |
| **Token details**    | Just `tokenAddress`         | Full token object (symbol, icon, decimals)        |
| **Market reference** | No direct link              | Includes `marketId` and full nested `market` data |
| **Claim action**     | Must find separately        | Included in nested `market.actions.claimRewards`  |
| **Parent position**  | Implicit (part of position) | Explicit `position` field linking to parent       |

See the [reward position type section](/markets/rewards#the-“reward”-position-type-recommended) for detailed examples of the recommended approach.


# Supported Protocols
Source: https://docs.dialect.to/markets/supported-protocols

We are constantly adding new protocols to the Markets and Positions API. Here is a list of the protocols we are currently supporting.

## List of Supported Protocols

<Check>
  Do you need more protocols or markets? Reach out to us at [hello@dialect.to](mailto:hello@dialect.to) and we'll add it to our roadmap.
</Check>

| Protocol                             | Markets Data | Positions Data | CTAs/Blinks |
| ------------------------------------ | ------------ | -------------- | ----------- |
| **Kamino Lend**                      | ✅            | ✅              | ✅           |
| **Kamino Borrow (formerly Markets)** | ✅            | ✅              | ✅           |
| **Kamino Multiply**                  | ✅            | ✅              | ✅           |
| **Kamino Leverage**                  | ✅            | 🔨             | ✅           |
| **Kamino LP**                        | 🔨           | 🔨             | ✅           |
| **Kamino Farms**                     | 🔨           | 🔨             | ✅           |
| **MarginFi Lending**                 | ✅            | 🔨             | ✅           |
| **Jupiter Lend Earn**                | ✅            | ✅              | ✅           |
| **Jupiter Lend Borrow**              | ✅            | ✅              | ✅           |
| **Raydium AMM**                      | 🔨           | 🔨             | ✅           |
| **Raydium CLMM**                     | 🔨           | 🔨             | ✅           |
| **Orca Whirlpools**                  | 🔨           | 🔨             | ✅           |
| **Meteora DLMM**                     | 🔨           | 🔨             | ✅           |
| **Drift Strategy Vaults**            | 🔨           | 🔨             | ✅           |
| **Lulo Protected Deposits**          | ✅            | ✅              | ✅           |
| **Lulo Boosted Deposits**            | ✅            | ✅              | ✅           |
| **Save Protected Deposits**          | 🔨           | 🔨             | ✅           |
| **DeFiTuna Lend**                    | ✅            | 🔨             | ✅           |
| **DeFiCarrot**                       | ✅            | 🔨             | ✅           |
| **DFlow Prediction Markets**         | ✅            | ✅              | 🔨          |

**Legend:** ✅ Available • 🔨 Coming Soon

## Market Types

* **Lending** - Deposit and borrow assets with real-time APY rates
* **Yield Aggregator** (soon) - Automated yield optimization strategies
* **Staking** (soon) - SOL and asset staking with reward tracking
* **Loop** - Leveraged position strategies (also called looping)
* **Perps** - Perpetual futures and leverage products
* **Prediction** - Bet on outcomes of real-world events
* **Market Making** (soon) - AMM, CLMM, and DLMM liquidity provision
* **Perps Liquidity Providing** (soon) - Perpetual futures liquidity strategies

To understand the different market types, as well as the supported protocols, and attributes, please refer to the [Market Types Section](/markets/market-types) page.


# MCP Integration
Source: https://docs.dialect.to/mcp-server/index

Connect AI agents to Dialect's blockchain infrastructure via Model Context Protocol.

Web3 development becomes conversational. Connect your AI agent to Dialect's full stack - APIs, documentation, blinks, market data, and alerts. Your agent gets complete access with built-in usage instructions and examples.

Perfect for building custom blinks in Cursor or integrating Dialect APIs.

## Quick Start

### Remote MCP Server (Recommended)

Our hosted MCP server is maintained for you and provides the best experience. Connect using one of these methods:

#### Using the Contextual Menu

For supported clients like Cursor, simply click the contextual menu button when viewing any page in the docs:

![Contextual Menu](https://res.cloudinary.com/dnxjhra4h/image/upload/f_auto,q_auto/v1754340439/dialect-docs/contextual-window-2.png)

This instantly configures the MCP server without any manual setup.

#### Manual Configuration

Choose your client below and start integrating:

<Tabs>
  <Tab title="Claude Code">
    Add the MCP server to your Claude Code configuration:

    ```bash theme={null}
    claude mcp add --transport http dialect-docs https://docs.dialect.to/mcp
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Go to Claude Desktop Settings:

    1. Connectors
    2. Add Custom Connector
    3. Paste the link into the URL field: [https://docs.dialect.to/mcp](https://docs.dialect.to/mcp)

    ![Claude Desktop Connectors](https://res.cloudinary.com/dnxjhra4h/image/upload/f_auto,q_auto/v1753984515/dialect-docs/connectors-claude-desktop.png)
  </Tab>

  <Tab title="Cursor">
    Add the MCP server to your Cursor settings:

    1. Open **Cursor Settings**
    2. Go to **Tools & Integrations** → **New MCP Server**
    3. Add the following server configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "dialect": {
          "url": "https://docs.dialect.to/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="General / Other Clients">
    For any MCP-compatible client, add this server URL:

    ```
    https://docs.dialect.to/mcp
    ```

    The server provides access to Dialect's full blockchain infrastructure including APIs, blinks, market data, and documentation.
  </Tab>
</Tabs>

### Local MCP Server

Run a local MCP server on your machine using our one-command installer:

```bash theme={null}
npx mint-mcp add dialect
```

This automatically detects your environment and configures the Dialect MCP server locally for Claude Desktop, Cursor, and other MCP clients.

## Core Features

<CardGroup>
  <Card title="Blinks" icon="hammer">
    Build your own blockchain links with custom logic and branding
  </Card>

  <Card title="Standard Blinks Library" icon="cube">
    Access 40+ pre-built protocol integrations ready to use
  </Card>

  <Card title="Markets API" icon="chart-bar">
    Query real-time rates, TVL, and protocol metrics across DeFi
  </Card>

  <Card title="Alerts & Notifications" icon="bell">
    Send multi-channel alerts and detect complex events
  </Card>

  <Card title="Documentation Search" icon="book-open">
    Search through all guides and examples for context
  </Card>

  <Card title="API Integration" icon="code">
    Access all Dialect endpoints with usage instructions
  </Card>
</CardGroup>


# Release Notes
Source: https://docs.dialect.to/release-notes/index

Latest updates and feature releases from the Dialect team

<Update label="April 6, 2026">
  ## Standard Blinks Library Updates

  * **Token-2022 Support for Jupiter** - Jupiter Blinks now support Token-2022 program tokens, including token program detection and associated token address resolution.

  ## Assets API Updates

  * **Token Deduplication** - Improved deduplication logic in the Assets API, now preferring Coinbase 50 Index tokens when resolving duplicates.
</Update>

<Update label="March 30, 2026">
  ## Standard Blinks Library Updates

  * **Smoke Tests Rollout** - Automated smoke tests across all protocol integrations. Each repo runs daily tests to ensure our SBL is working as expected.
  * **Kamino SDK Update** - Bumped Kamino liquidity SDK to v11 including related refactoring and smoke test fixes.

  ## Assets API Updates

  * **List Endpoint** - New endpoint that lists all available assets from the asset catalog.

  ## Markets API Updates

  * **History Prefill Parameters** - Added `marketIds` and `startTime` parameters for prefilling values on the history endpoint.

  ## Accessibility & SEO Improvements

  * **Accessibility Improvements** - Added alt attributes to all images and videos for better accessibility.
  * **Link & Redirect Fixes** - Redirects for legacy URLs, namespaces in SBL and broken links.
</Update>

<Update label="March 23, 2026">
  ## Assets API Updates

  * **API Key Authentication** - API key authentication is now enforced on the Assets API. All requests must include a valid API key.

  ## Markets API Updates

  * **Client Key Authentication** - Client key authentication is now enforced on the Markets API. All requests must include a valid client key. Get in touch with us to [request yours](/markets/api-keys).

  ## Documentation Updates

  * **API key guides** - Each section of our docs now includes an API key section with instructions on how to request your API key. A general [Request API Keys](/request-api-keys) page is also available for easy navigation.
</Update>

<Update label="March 16, 2026">
  ## Standard Blinks Library Updates

  * **OpenAPI Automation** - Automated OpenAPI spec generation rolled out across all protocol integrations. Each protocol now auto-generates validated, Mintlify-compatible API documentation:
    * [Kamino](/api-reference/kamino)
    * [Meteora](/api-reference/meteora)
    * [Orca](/api-reference/orca)
    * [Drift](/api-reference/drift)
    * [Raydium](/api-reference/raydium)
    * [Save](/api-reference/save)
    * [MarginFi](/api-reference/marginfi)
    * [Lulo](/api-reference/lulo)
    * [DefiCarrot](/api-reference/deficarrot)
    * [DefiTuna](/api-reference/defituna)
  * **Kamino SDK Bugfix**: Fixed an SDK bump issue in Kamino Blinks along with general refactoring improvements.
  * **Protocol API Namespace Restructure**: API reference URLs restructured from flat `api-reference/{tag}/{operation}` to namespaced `api-reference/{protocol}/{tag}/{operation}`, resolving URL collisions between protocols sharing the same tag names (e.g. "Lend" used by DefiTuna, MarginFi, and Kamino). Redirects in place for all legacy URLs.
</Update>

<Update label="March 9, 2026">
  ## Markets API Updates

  * **Asset Filter Update** - Asset filtering on [`GET /v0/markets`](/api-reference/markets/list-all-markets) now requires an explicit `type` parameter and excludes prediction markets, as filtering by a common asset like USDC across prediction markets would return unmanageable amounts of data.
  * **New PnL Endpoint** - New [`GET /v0/positions/pnl`](/api-reference/positions/get-pnl-data-for-wallet-positions) endpoint returns realized and unrealized PnL for prediction market positions, including closed positions. [Learn more](/markets/market-types/prediction)
  * **Capital Tracking Fields** - Both `/v0/positions/pnl` and `/v0/positions/owners` now include capital fields (`invested`, `investedLifetime`, `netFlow`, `netFlowLifetime`) per prediction position, giving the data needed to show users their current exposure and whether they've broken even.
</Update>

<Update label="March 2, 2026">
  ## Developer Tooling

  * **Solana DeFi Yield Dashboard** - New open-source Next.js showcase app demonstrating how to build a full DeFi yield dashboard using the Markets API, Positions API, and Standard Blinks Library. Includes a live yield table, wallet-connected position tracking, and one-click deposits. [View on GitHub](https://github.com/dialectlabs/defi-dashboard)

  ## Positions API Updates

  * **PnL for Prediction Market Positions** - The Positions API now returns PnL data for prediction market positions, including total, realized, unrealized, and lifetime PnL fields per position. [Learn more](/markets/market-types/prediction)

  ## Markets API Updates

  * **Asset Filter** - [`GET /v0/markets`](/api-reference/markets/list-all-markets) now accepts an `asset` query parameter to filter markets by mint address (comma-separated, combinable with existing filters).

  * **Lulo Market Updates** - Added missing `websiteUrl` field to Lulo markets and renamed `productName` from `Boosted` to `Boost`
</Update>

<Update label="February 24, 2026">
  ## Standard Blinks Library Updates

  * **Kamino: ATA Creation Test Coverage** - Extended the smoke test suite with new wallets and end-to-end coverage for ATA creation flows, targeting wallets with no existing lending positions.

  ## Developer Tooling

  * **Automated OpenAPI Spec Pipeline** - Introduced an automated pipeline that monitors protocol OpenAPI specs for changes and keeps our API reference documentation up to date. Lulo is the first protocol integrated into this workflow.
</Update>

<Update label="February 16, 2026">
  ## Prediction Markets: Cost Basis Tracking

  Added [Cost Basis](/markets/market-types/prediction#cost-basis) documentation to our Prediction Markets guide. The Positions API now includes cost basis data for prediction market positions, giving insight into average entry prices and total capital committed. Cost basis is calculated using the **average cost method** — the same approach used by traditional brokerages.

  The documentation covers how buys, sells, full exits, and transfers affect cost basis calculations, with step-by-step examples.

  ## Standard Blinks Library Updates

  * **Jupiter Earn Bugfix** - Fixed a duplicate create account instruction in Jupiter Earn deposits, resolving transaction failures for wallets without an existing token account
  * **Expanded Test Coverage** - Improved test suite with dedicated test wallets and end-to-end coverage for first-time deposit scenarios
</Update>

<Update label="February 9, 2026">
  ## Prediction Markets API Documentation

  Added DFlow Prediction Markets API documentation to our [Prediction Markets](/markets/market-types/prediction) guide. DFlow is the official provider for Kalshi, bringing real-world event prediction markets to Solana.

  ## Solana Scaffold Updates

  Monthly maintenance updates to the [Solana Blink Starter](/blinks/blinks-starters/solana) including dependency upgrades, Dependabot integration, and automated CI workflows for improved code quality and security.

  ## Monad Scaffold Deprecation

  The Monad scaffold has been deprecated in favor of our more flexible [EVM Scaffold](/blinks/blinks-starters/evm), which supports all EVM-compatible chains including Monad.

  ## Standard Blinks Library Updates

  Infrastructure and reliability improvements:

  * **Jupiter Blinks** - Fixed lending blinks and moved to the new Jupiter API endpoints
  * **Kamino Blinks** - Consolidated smoke tests and improved test coverage using Dialect's demo wallet
  * **MarginFi Blinks** - Fixed token identification to use mint addresses instead of token tickers for better reliability and SDK bump
</Update>

<Update label="February 2, 2026">
  ## Dialect Developer Updates on Telegram 🚀🚀🚀

  We've launched an official developer updates channel on Telegram. Get bite sized, dev friendly summaries of our weekly release notes delivered directly to your inbox.

  [Join the channel](https://t.me/+cpAV3GVEpvpiNjIy) to stay up to date with the latest features, API improvements, and more.

  ## Prediction Markets Documentation Updates

  Enhanced the [Prediction Markets](/markets/market-types/prediction) documentation with examples for filtering positions by `market.status` (`open`, `closed`, `settled`) on the [Positions endpoint](/api-reference/positions/list-all-market-positions-by-wallet-address).

  Have feedback on what additional filtering you'd like to see? Let us know at [hello@dialect.to](mailto:hello@dialect.to).

  ## Markets API Updates

  * **New Field: `productName`** - All market types now include a `productName` field for better identification of specific market products
  * **Removed `oraclePrice`** - The `oraclePrice` parameter has been removed from lending markets
  * **New Field: `marketName`** - All loop (multiply) market types now include a `marketName` field in the `additionalData` object for better identification of specific market names

  For full details, please refer to the [Markets API Reference](/api-reference/markets/list-all-markets) page.

  ## Standard Blinks Library Updates

  * **MarginFi SDK** - Updated to the latest MarginFi SDK with new implementation details for improved reliability
  * **Jupiter API Migration** - Migrated lend and swap functionality to Jupiter's new APIs
</Update>

<Update label="January 26, 2026">
  ## Prediction Markets Documentation

  Added documentation for [Prediction Markets](/markets/market-types/prediction) - a new market type enabling users to trade on the outcomes of real-world events. The guide covers how prediction markets work, supported protocols, and integration examples for building prediction market experiences.

  ## Assets API Updates

  Enhanced [search](https://assets.dial.to/api/docs#tag/assets/GET/v0/search) capabilities for the Assets API:

  * **Expanded Data Sources** - Search now queries additional data providers for improved asset discovery
  * **Improved Data Quality** - Various changes to reach enhanced metadata accuracy and consistency across search results
  * **Metadata Fallback Chain** - Added fallback logic to ensure asset metadata is always available even when primary sources are unavailable

  ## Positions API Updates

  * **Prediction Markets GA** - Prediction market position tracking is now generally available. The `prediction_beta` filter parameter introduced on January 13 is no longer required. [Learn more](/api-reference/positions/list-all-market-positions-by-wallet-address)
  * **Market Type Filtering** - Filter positions by market type using the new `type` parameter. Supported types: `yield`, `lending`, `loop`, `perpetual`, `reward`, and `prediction`. Currently supports filtering by one type per request. [Learn more](/api-reference/positions/list-all-market-positions-by-wallet-address)
</Update>

<Update label="January 19, 2026">
  ## Introducing the Assets API

  We're excited to launch the [**Assets API**](https://assets.dial.to/) — a unified endpoint for token metadata, pricing, and asset information across multiple chains. No more juggling multiple data sources or maintaining separate integrations for each blockchain.

  ## Key Benefits

  * **Single Integration** - Access crypto assets across major chains through one unified API
  * **Real-Time Pricing** - Get up-to-date price data with built-in caching for optimal performance
  * **Historical Data** - Track price movements over time for analytics and charting

  ### Coverage

  * **Multi-Chain Support** - Solana, Ethereum, and major L1 chains are now accessible through a single API
  * **Asset Types** - Crypto tokens and real-world assets, including stocks
  * **Token Format** - For Solana and Ethereum, we use the token address as the asset ID (e.g. `solana:So11111111111111111111111111111111111111112`), for all other chains, please use the search endpoint to find the corresponding asset ID

  ### Available Endpoints

  | Endpoint                                                                                                | Description                                                 |
  | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
  | [`GET /v0/search`](https://assets.dial.to/api/docs#tag/assets/GET/v0/search)                            | Search for assets by `name`, `ticker` or `tags`             |
  | [`GET /v0/assets/{id}`](https://assets.dial.to/api/docs#tag/assets/GET/v0/assets/\{id})                 | Retrieve detailed metadata and pricing for a specific asset |
  | [`GET /v0/assets/{id}/history`](https://assets.dial.to/api/docs#tag/assets/GET/v0/assets/\{id}/history) | Get historical price data for an asset                      |

  ### Documentation

  Full API documentation with coverage details, caching information, and examples is available at [assets.dial.to/api/docs](https://assets.dial.to/api/docs).

  ## Markets API Updates

  * **Market Types**: Enhanced documentation with new [Market Types](/markets/market-types/introduction) coverage, explaining how different DeFi strategies work and how to use our APIs to integrate them. Each market type includes detailed guides with data structures, supported protocols, and integration examples:
    * [Yield Markets](/markets/market-types/yield),
    * [Lending Markets](/markets/market-types/lending),
    * [Loop Markets](/markets/market-types/loop), and
    * [Perpetual Markets](/markets/market-types/perpetual)

  * **Pagination Support** - Markets endpoint now supports cursor-based pagination with configurable limits for efficient data retrieval

  * **CDN-Hosted Images** - Token images now served via CDN for improved performance

  * **Query Improvements** - API now accepts `type` and `provider` parameters as comma-separated values for flexible filtering
</Update>

<Update label="January 13, 2026">
  ## Positions API Updates

  Enhanced position tracking support:

  * **Prediction Markets** - Positions API now supports prediction market positions. This feature is still in beta. To use it, you need to add the `prediction_beta` filter parameter to your request. [Learn more](/api-reference/positions/list-all-market-positions-by-wallet-address)

  ## Standard Blinks Library Updates

  Documentation improvements and enhanced protocol coverage:

  * **Supported Protocols Documentation** - Updated supported protocols page with current protocol coverage and capabilities
  * **Documentation Fixes** - Fixed broken links and improved documentation clarity across multiple endpoints
</Update>

<Update label="January 6, 2026">
  ## Happy New Year from the Dialect Team!

  Wishing everyone a fantastic 2026! We're excited to kick off the new year with continued improvements to our APIs and documentation. Thank you for building with Dialect — here's to another year of shipping great products together.

  ## New Release Notes Format

  From now on our release notes will be structrued as a changlog with weekly updates. Instead of creating one entry per month and updating weekly, we will be transparently logging all changes made each week. This will provide better visibility into our development process and allow you to track improvements more granularly.

  ## Positions API Updates

  * **Atomic Rewards** - Positions API now returns atomic reward entries instead of reward arrays, with a new dedicated reward position type that ensures rewards remain visible even after positions are closed. [Learn more](/markets/rewards#positions-api-rewards)
</Update>

<Update label="December 2025">
  ## Positions API Updates

  * **Prediction Markets API**: Prediction markets API deployed with filtering capabilities, allowing position queries with `prediction_beta` filter parameters for tracking prediction market positions [View API docs](/api-reference/positions/list-all-market-positions-by-wallet-address)
  * **Rewards Type**: We're introducing a new `reward` type to the Positions API, allowing you to track the rewards earned from your positions. This was necessary to ensure you can track rewards even from positions that have been closed [View more](/markets/rewards)
  * **Atomic Rewards**: Positions API now returns atomic reward entries instead of reward arrays, with a new dedicated reward position type that ensures rewards remain visible even after positions are closed [View more](/markets/rewards#positions-api-rewards)

  ## Blinks SDK Updates

  * **Registry link update** - Updated an outdated link to the blink registry documentation [View SDK](https://github.com/dialectlabs/blinks)
</Update>

<Update label="November 2025">
  ## Standard Blinks Library Updates

  Enhanced documentation, protocol improvements, and new protocol support:

  * **Kamino Borrow Blinks** - Added support for Kamino Borrow full lifecycle support. Repay with collateral operations now fully withdraw tokens, and borrow operations may leave trace dust amounts. We also did improvements to the blinks to ensure they are more reliable and secure
  * **Lulo Protocol Improvements** - Added improved error handling and retry logic for Lulo protocol operations
  * **DeFiCarrot Integration** - Added DeFiCarrot blinks allowing users to mint and redeem CRT tokens right from the protocol [View API docs](/api-reference/earn/get-mint-blink)
  * **Why SBL Section** - Added new documentation explaining the benefits and use cases for Standard Blinks Library, helping developers understand when and why to use SBL [View guide](/standard-blinks-library/why-sbl)
  * **Quick Start Guide** - New quick start guide to help developers integrate SBL faster [View guide](/standard-blinks-library/quick-start)
  * **Kamino Account Closure Notification** - Added a notification to the Kamino withdraw endpoints, informing devs that our blinks will automatically close the account when the withdrawal amount is >= 99.9% [View API docs](/api-reference/markets/market-reserve-withdraw)

  ## Markets API Updates

  New protocol support, quick start guide, and enhanced rewards functionality:

  * **Kamino Borrow Blinks** - Complete Lending Lifecycle Support. Added blink URLs for borrow, repay, and repayWithCollateral operations in Markets API responses, providing developers access to the complete lending workflow directly from the API [View API docs](/api-reference/markets/list-all-markets)
  * **DeFiCarrot** - Added DeFiCarrot support to Markets API, providing blinks for minting and redeeming CRT tokens [View API docs](/api-reference/markets/list-all-markets)
  * **Quick Start Guide** - New quick start guide for Markets API integration [View guide](/markets/quick-start)
  * **Kamino Lend Claim Rewards Blink**: Added claim rewards blink to Positions API response, providing direct links to claim rewards transactions [View API docs](/api-reference/markets/list-all-markets)
  * **Kamino Lend Vault Name**: Added vault name to Markets API response, providing a human readable name for the vault [View API docs](/api-reference/markets/list-all-markets)

  ## Positions API Updates

  Heavy performance and reliability improvements for the endpoint as well as:

  * **Kamino Lend Claim Rewards Blink**: Added claim rewards blink to Positions API response, providing direct links to claim rewards transactions [View API docs](/api-reference/positions/list-all-market-positions-by-wallet-address)

  ## Alerts API Updates

  Enhanced push notification documentation:

  * **Enhanced Push Notifications Setup Documentation** - Enhanced documentation for service account credentials setup with clearer prerequisites and step-by-step Firebase integration requirements [View docs](/alerts/integrate-inbox/api/push-notifications)
  * **Custom Data in Notifications**: Added an arbitrary data field to notifications, allowing you to store custom data in notifications. <br /> [Integrate Custom Data](/alerts/integrate-inbox/api/notifications#working-with-custom-data) | [Send Alerts](/alerts/send/api/send-messages#step-4%3A-custom-data) | [OpenAPI Spec](/api-reference/integrate-an-inbox/get-notification-history)
  * **Notification Delivery Improvements** - Improved notification delivery for Telegram and email channels,
    ensuring even more reliable delivery across all communication channels
</Update>

<Update label="October 2025">
  ## Historical Position Data

  Track your DeFi portfolio's evolution over time with our new historical data endpoint - perfect for analytics, performance tracking, and portfolio visualization:

  **What it is:** Historical Position Data provides cumulative value snapshots of wallet positions across all supported protocols. Query a date range to see how positions have changed, including yield accumulation, deposits, and withdrawals.

  **Key Benefits:**

  * **Portfolio Analytics** - Build performance dashboards tracking total value over time
  * **Historical P\&L** - Calculate returns and analyze position performance across protocols
  * **Time-Series Visualization** - Create charts showing portfolio growth and changes

  **Available from:** October 8, 2025 onwards (backfilling to earlier dates coming soon)

  [Learn more about historical data](/markets/history) | [Try the API](/api-reference/positions/get-historical-position-snapshots)

  ## Positions API Updates

  Enhanced position tracking with new protocol support and infrastructure improvements:

  * **Multiple Signers Fix** - Resolved position indexing issues when transactions have multiple signers, ensuring accurate position tracking across all scenarios
  * **Jupiter Borrow Support** - We've added Jupiter Borrow protocol support to the Positions API, enabling real-time position tracking for Jupiter's lending positions. [Test the Positions API](/api-reference/positions/list-all-market-positions-by-wallet-address)
  * **Resolution Parameter** - Added configurable time intervals (1m, 5m, 1h, 1d) to historical position snapshots endpoint for more granular data queries and optimized charting. [Learn more](/markets/history#resolution)

  ## Markets API Updates

  Enhanced market data with historical APY tracking and expanded protocol coverage:

  * **DeFiTuna** - Added DeFiTuna lending protocol support to Markets API, providing real-time market data for DeFiTuna's lending markets. [View API docs](/api-reference/markets/list-all-markets)
  * **Kamino Lend Rewards** - Added rewards data for Kamino Lend markets, showing additional incentives and rewards available for lending positions
  * **Data Consistency Improvements** - Enhanced indexing infrastructure for improved data consistency across all supported protocols
  * **Historical APY Data** - Markets API now returns 30-day, 90-day, and 180-day historical APY averages for both deposits and borrows, enabling better rate trend analysis and forecasting. [View API docs](/api-reference/markets/list-all-markets)

  ## Standard Blinks Library Updates

  Enhanced protocol support and infrastructure improvements:

  * **DeFiTuna Integration** - Added DeFiTuna lending protocol with deposit and withdraw blinks for earning yield on deposits. [View API docs](/api-reference/lend/lend-deposit)
  * **Full Jupiter Borrow Support** - Jupiter Borrow now supports the full lending lifecycle with deposit, withdraw, borrow, and repay blinks so that you can build complete DeFi lending experiences. [View API docs](/api-reference/lend-borrow/deposit)
  * **Jupiter API Migration** - Updated Jupiter Swap blink to use the latest Jupiter API endpoints ensuring continued reliability and compatibility. [View Docs](/api-reference/swap/swap-token)
  * **Kamino Lend Vaults** - Added Kamino Lend support with deposit, withdraw and claim rewards blinks [View API docs](/api-reference/lend/get-lend-vault-deposit-blink)
  * **Kamino Farms** - Added Kamino Farms support enabling users to claim rewards from farming positions. [View API docs](/api-reference/farms/claim-farm-rewards)
  * **Kamino Markets Renaming** - Renamed Kamino Lending endpoints to Kamino Markets, using "market reserve" terminology instead of "lending reserve" to better reflect Kamino's renaming. [View API docs](/api-reference/markets/market-reserve-deposit)
  * **Kamino Multiply & Leverage** - Enhanced support for multiply and leverage positions handling
  * **Kamino Multiply Deposit Fix** - Resolved multiple issues with Kamino multiply deposit blinks including LUT (Lookup Table) problems, transaction size optimization, and missing instructions
  * **Lulo Protocol Fix** - Resolved endpoint parameter issues

  ## Blinks in Alerts

  Blinks in Alerts lets you embed blockchain actions directly into our alerts stack so that your users can swap tokens, deposit funds, or execute any onchain action without leaving your app.

  **Key Benefits:**

  * **Instant Actions** - Users take onchain actions directly from notifications without app switching
  * **Higher Conversion** - Reduce friction between alert and action, improving user engagement
  * **No in-app browser** - Users don't need to leave your app to complete onchain actions

  [Learn more](/alerts/blinks-in-alerts)
</Update>

<Update label="September 2025">
  ## Standard Blinks Library Updates

  Continued expansion of our production-ready protocol integrations with enhanced transaction capabilities and new lending protocol support:

  * **Kamino Multiply Enhancement** - Multiply deposit blinks now support returning multiple transactions in a single call, enabling combined operations like account creation and deposit simultaneously
  * **Jupiter Lend Earn Blinks** - Added Jupiter Earn lending protocol with support for deposit and withdrawal actions
  * **Jupiter Lend Borrow Blinks** - Added deposit functionality for Jupiter's lending protocol. Please make sure you read the notes before integrating.
  * **OpenAPI Enhancements** - Added percentage preset values across all protocol endpoints (Jupiter, Drift, Kamino, Orca, Raydium, Save, Meteora, MarginFi, Lulo) for improved API testing experience
  * **MarginFi Withdraw Fix** - Resolved critical production issue preventing withdrawals from MarginFi lending positions

  ## Markets API Updates

  Enhanced [API responses](/api-reference/markets/list-all-markets) with richer metadata for improved developer experience and support for Jupiter's lending protocol:

  * **Jupiter Lend** - Get up to date market's data such as APY, TVL, and more information for Jupiter's Borrow and Earn protocols with a single API call.
  * **Kamino Lending Rewards** - Added reward incentives data showing additional APY earned from platform rewards (e.g., earning ADX tokens for USDC deposits)
  * **Token Icons** - Added token icon URLs directly in API responses, eliminating the need for separate token metadata API calls
  * **Protocol Icons** - Added provider icon URLs for complete branding support
  * **Website URLs** - Integrated direct deep links to specific markets on each protocol's website for seamless user navigation

  ## Positions API Updates

  Enhanced position tracking with performance improvements and richer metadata:

  * **Jupiter Earn Positions** - Get real-time position tracking for your Jupiter Earn deposits and earnings through our unified Positions API.
  * **Performance Optimizations** - Significant improvements by optimizing our indexing process, delivering faster data access across all supported protocols
  * **Kamino Lending Rewards** - Added reward data for user positions, showing earned incentives alongside position details
  * **Enhanced Metadata** - Added token and protocol icons as well as website URLs directing the user to the position's market on the protocol's website for complete UI development
  * **Rewards Data** - Positions now return reward token information including token addresses and amounts earned, providing complete visibility into DeFi incentives

  ## Events System Updates

  New personalized trading capabilities for portfolio monitoring:

  * **Last Trade Events** - Track price changes and receive alerts when tokens move up/down by a certain threshold since your last buy. [Learn more](/alerts/events/price-change#trade-based-price-changes-last-trade)
</Update>

<Update label="August 2024">
  ## Send API Updates

  We've updated our Send API to support multicast messaging, enabling you to send messages to up to **10,000 subscribers** at once through our [`/v2/{appId}/send`](/api-reference/send-alerts/send-alert) endpoint. This dramatically improves performance for applications with large subscriber bases.

  * **Multicast Messaging** - Send alerts to up to 10,000 subscribers in a single API call using the `subscribers` recipient type
  * **Enhanced Performance** - Significantly reduced latency and improved throughput for bulk notifications
  * **Flexible Targeting** - Choose between individual, multicast (up to 10K), or all-subscribers delivery options
  * **Existing API Compatibility** - Seamless integration with current alert workflows and channel configurations

  Test via [dashboard](/alerts/send/dashboard#sending-dashboard-alerts) or [Send Alerts API documentation](/alerts/send/api/send-messages).

  ## Dashboard v2 released

  We've released our new dashboard v2, featuring a complete redesign with enhanced functionality and improved user experience across all project management workflows.

  ### Key Features & Improvements:

  * **Send Alerts** - Send alerts to your subscribers with no-code
  * **API Key Management** - Manage your project's API keys in a single place
  * **Settings Panel** - Configure your project's details

  ### Getting Started:

  * **[Dashboard Introduction →](/alerts/setup/dashboard-introduction)** - Connect wallet and set up your project
  * **[Send your first alert →](/alerts/send/dashboard)** - Try no-code message sending
  * **[Test the live demo →](https://alerts-example.dialect.to)** - Experience the notification flow firsthand

  Access the new dashboard at [dashboard.dialect.to](https://dashboard.dialect.to).

  ## Feedback Blink Tutorial

  We've added a new tutorial, explaining how to collect feedback from users using a blink. Data is stored off-chain and we use message signing to ensure it's gas-free. This tutorial is available in the [guides section](/blinks/blinks-provider/guides/feedback-blink).

  ## EVM Scaffold Launch

  We've launched our new **EVM Scaffold**, providing enhanced web3 development capabilities across EVM-compatible chains.

  * **Multi-Chain Support** - Works across all EVM-compatible networks
  * **Modern Stack** - Built with the latest Web3 development best practices and tooling
  * **Migration Path** - Monad scaffold will be sunset soon in favor of this more flexible solution

  Get started with the [EVM Scaffold](/blinks/blinks-starters/evm).

  ## Events System (Beta) Launch

  We've launched our [**Events System**](/alerts/events) - providing real-time detection and delivery of blockchain-specific events with no complex monitoring infrastructure required. Events can be used standalone via webhook delivery or bundled with Dialect's Alerts Stack as off-the-shelf topics, enabling developers to integrate onchain and market events into their products for timely user alerts, custom wallet capabilities, or trading tools.

  * **Real-time Event Detection** - Advanced sliding window analysis for price changes and filtering for newly-launched tokens
  * **Price Change Events** - Configurable thresholds and time periods with precise percentage-based detection. [View Price Change Events docs](/alerts/events/price-change)
  * **New Token Events** - Community audit criteria and advanced filtering for token launches. [View New Token Events docs](/alerts/events/trending-token)
  * **Webhook Integration** - Direct webhook delivery or integration with Dialect's Alert Stack for multi-channel notifications
  * **Beta Access** - Currently requires early access request. [Get started with Events](/alerts/events)

  ## Standard Blinks Library Updates

  Continued expansion of our production-ready protocol integrations with new leverage trading capabilities:

  * **Kamino Multiply Blinks** - Added leverage trading blinks for Kamino Finance multiply strategies. [View in docs](/api-reference/leverage/leverage-setup)

  ## Markets API Updates

  Enhanced protocol coverage with new integrations:

  * **Kamino Multiply Integration** - Markets and Positions APIs now support Kamino multiply strategies, providing real-time data for leveraged positions alongside our new multiply blinks. [View Markets API docs](/api-reference/markets/list-all-markets)

  ## MCP Server Hosting & Enhanced Developer Experience

  Major improvements to our [Model Context Protocol integration](/mcp-server) with hosted infrastructure and simplified setup:

  * **Hosted MCP Servers** - MCP servers now fully hosted (no longer require local mode setup)
  * **One-Click Integration** - New contextual menu support enables instant MCP setup from any documentation page
  * **Multi-Client Support** - Enhanced compatibility with Claude Code, Claude Desktop, Cursor, ChatGPT and other AI development environments
</Update>

<Update label="July 2025">
  ## React SDK Updates

  Major widget redesign with enhanced user experience and v2 API migration:

  * **Widget UI Revamp** - Complete redesign of settings screen with improved UX and modern interface
  * **v2 Migration** - Enhanced channel management and notification controls using v2 API. [View API reference](/api-reference/manage-channels/get-channels)
  * **Live Demo** - Experience the new widget at [alerts-example.dialect.to](https://alerts-example.dialect.to/)

  ## Positions API

  We've launched our new **Positions API** - a unified way to track wallet positions across multiple DeFi protocols. Instead of querying each protocol individually, developers can now get position data through a single API endpoint.

  * **New API Launch** - Real-time per-wallet positions tracking across multiple DeFi protocols with unified data access. [View API reference](/api-reference/positions/list-all-market-positions-by-wallet-address)
  * **Demo Integration** - Funded demo wallet with active Kamino positions for realistic API testing
  * **Enhanced Protocol Support** - Added Kamino Lending and Lulo protocol support to position tracking documentation

  ## Markets API Updates

  Enhanced protocol coverage with new lending protocol integration:

  * **Lulo Protocol** - Added Lulo lending protocol support with protected and boosted deposits. [View Markets API docs](/api-reference/markets/list-all-markets)

  ## Alerts API Updates

  Enhanced notification management capabilities and new channel endpoints:

  * **Channel Management Endpoints** - Complete suite of 7 new endpoints for email and Telegram channel management. [View API reference](/api-reference/manage-channels/get-channels)
  * **OpenAPI Documentation** - Fully documented channel endpoints with examples, schemas, and integration guides
  * **Clear Notification History** - New endpoint for clearing all read alerts with safety controls. [View API reference](/api-reference/integrate-an-inbox/clear-notification-history)
  * **Authentication Token Lifetime** - Updated authentication documentation to specify that auth tokens have a 1-year lifetime. [View Authentication docs](/alerts/integrate-inbox/api/authentication)

  ## Standard Blinks Library Updates

  Continued expansion of our production-ready protocol integrations with enhanced developer experience:

  * **Kamino Multiply Blinks** - Added Kamino multiply blinks to enable leveraged DeFi strategies through the Standard Blinks Library
  * **Jupiter Integration** - Added Jupiter token swap APIs to Standard Blinks Library. [View Jupiter API docs](/api-reference/swap/swap-token)
  * **One-Click API Testing** - All Standard Blinks Library endpoints now include prefilled demo values. Developers can test any endpoint immediately by clicking "Try the API" - no need for existing DeFi positions or manual data entry
  * **Save Protocol** - Added lending protocol support with protected and boosted deposits. [View Save API docs](/api-reference/lending/lending-deposit-token)
  * **Enhanced Orca Endpoints** - Updated Orca APIs with position parameter support, reducing required inputs for streamlined integration

  ## Developer Experience Updates

  Enhanced tools and documentation for improved development workflow:

  * **Mobile Alerts Stack** - Updated mobile alerts stack landing page with improved user experience and interface
  * **Mintlify Integration** - Improved "Try the API" functionality with pre-filled demo data for seamless testing across all Standard Blinks Library endpoints
  * **Scaffold Updates** - Upgraded dependencies and `action.json` for Monad scaffold
</Update>

<Update label="June 2025">
  ## AI-Powered Development with MCP Integration

  We've launched our **Model Context Protocol (MCP)** integration, bringing conversational Web3 development to your favorite AI tools. Now you can build, fetch, integrate and share Blinks or Alerts directly through Cursor, and any other AI development environments.

  * One-command setup: `npx mint-mcp add dialect`
  * Full access to Dialect's APIs through natural language
  * Built-in documentation search with AI-powered contextual results
  * Perfect for rapid Blinks development and API integration

  Learn more in the [MCP docs](/mcp-server).

  ## Markets API (Beta) Launch

  Introducing **Markets** - real-time market data from Solana's top lending protocols, unified in a single API. Get APYs, TVL, and liquidity data with ready-to-use Blinks for seamless DeFi interactions.

  * Real-time lending rates across MarginFi and Kamino
  * Comprehensive market data (deposits, borrows, limits, token metadata)
  * Pre-built transactions for deposits and withdrawals
  * No need to learn individual protocol SDKs

  Learn more in the [Markets docs](/markets).

  ## Universal Inbox with Jupiter Partnership

  The **Universal Inbox** breaks down notification silos across Web3 applications. Users can now receive notifications from multiple subscribed apps in one unified feed.

  * Single notification feed across all Web3 apps
  * Cross-app subscriptions (e.g., Drift liquidation alerts while using Jupiter Mobile)
  * Granular control over which apps to receive notifications from
  * Unified message history with cross-channel delivery

  Learn more in the [Universal Inbox guide](/alerts/integrate-inbox/universal-inbox).

  ## Standard Blinks Library Expansion

  Our **Standard Blinks Library (SBL)** now covers 8+ major Solana protocols with production-ready Blink APIs. Each integration includes optimized metadata, built-in error handling, and zero SDK complexity.

  New protocol integrations:

  * **Jupiter** - Token swaps with best-price routing
  * **Raydium** - CLMM pools, AMM pools, and RAY staking
  * **Orca** - Whirlpools (concentrated liquidity)
  * **Meteora** - Token launches and DLMM pools
  * Plus enhanced coverage for Kamino, MarginFi, Drift, and Lulo

  Learn more in the [Standard Blinks Library docs](/standard-blinks-library).

  ## Alerts Documentation Revamp

  We've completely revamped our alerts documentation with improved structure, clearer examples, and comprehensive guides for all use cases.

  * Improved event detection and monitoring system
  * Mobile Alert Stack with push notification support
  * Restructured documentation with better navigation and examples

  Explore the new [Alerts documentation](/alerts).

  ## Documentation Search Improvements

  Our documentation now includes AI-powered search capabilities, making it easier to find relevant guides, examples, and API references across our entire developer ecosystem.

  * AI-powered contextual search results
  * Faster discovery of relevant documentation
  * Improved developer experience when working with Dialect APIs and SDKs
</Update>


# Request API Keys
Source: https://docs.dialect.to/request-api-keys

Get your API keys for Dialect's products.

<img alt="Request API Keys" />

Choose your product to get started.

<Card title="Alerts" icon="bell" href="/alerts/api-keys">
  Request access to send notifications to your users in under 15 minutes.
</Card>

<Card title="Standard Blinks Library" icon="book" href="/standard-blinks-library/api-keys">
  Request access to integrate Solana protocols with simple HTTP requests.
</Card>

<Card title="Markets & Positions" icon="building-columns" href="/markets/api-keys">
  Request access to real-time market data and position tracking across Solana
  DeFi.
</Card>


# Request API Keys
Source: https://docs.dialect.to/standard-blinks-library/api-keys

Request your API keys to access the Standard Blinks Library APIs and integrate Solana protocols with simple HTTP requests.

<img alt="Request API Keys for Standard Blinks Library" />

To request your API keys for our Standard Blinks Library, or you have any questions about API keys or need assistance, reach out to us at [hello@dialect.to](mailto:hello@dialect.to).


# Standard Blinks Library
Source: https://docs.dialect.to/standard-blinks-library/index

Production-ready APIs to construct transactions for Solana's top protocols. Instantly bring on-chain experiences into your app today.

<img alt="Standard Blinks Library - Ready-to-use protocol endpoints" />

The Standard Blinks Library (SBL) provides production-ready APIs for creating transactions with Solana's most popular protocols. Instead of building integrations from scratch or learning complex protocol SDKs, use our tested endpoints to bring DeFi experiences into your app with simple HTTP requests.

## Supported Protocols

We support major protocols like Jupiter, Kamino, Raydium, Orca, Meteora, and more. For the complete list of available integrations, visit our [Supported Protocols](/markets/supported-protocols) page or browse protocols in the left sidebar menu.

<Tip>
  Don't see what you're looking for? New protocols are added regularly — contact us at [hello@dialect.to](mailto:hello@dialect.to) and we'll help you get started.
</Tip>

## Get Started

<CardGroup>
  <Card title="Why SBL?" icon="lightbulb" href="/standard-blinks-library/why-sbl">
    Learn why teams are choosing APIs over SDKs for protocol integrations
  </Card>

  <Card title="Quick Start" icon="rocket" href="/standard-blinks-library/quick-start">
    Build your first integration in 5 minutes with zero SDK complexity
  </Card>

  <Card title="Browse Protocols" icon="grid" href="/api-reference/swap/swap-token">
    Explore ready-to-use APIs for swaps, lending, liquidity, and more
  </Card>
</CardGroup>


# Getting Started with the Standard Blinks Library
Source: https://docs.dialect.to/standard-blinks-library/quick-start

Learn how to integrate Solana's top protocols into your application through pure HTTP requests.

The Standard Blinks Library (SBL) is a collection of APIs that return ready-to-sign transactions for major Solana protocols. By abstracting away the complexity of integrating these protocols through complex SDKs and maintaining these integrations, the SBL allows you to focus on building a seamless user experience.

Each SBL API endpoint follows the [Solana Actions specification](https://solana.com/docs/advanced/actions) and provides:

<CardGroup>
  <Card title="Ready-to-Sign Transactions" icon="signature">
    APIs that return transaction data ready for user signing
  </Card>

  <Card title="Rich UI Metadata" icon="sparkles">
    Optimized metadata for building beautiful user experiences
  </Card>

  <Card title="Clear Error Handling" icon="circle-exclamation">
    User-friendly error messages for better debugging
  </Card>
</CardGroup>

## What You'll Learn

By the end of this guide, you'll understand how to:

* Fetch blink metadata (titles, descriptions, parameters)
* Build POST requests with user wallet addresses and parameters
* Handle transaction responses
* Sign and send transactions to Solana

## Understanding Blinks

Blinks (blockchain links) are URLs that return ready-to-sign transactions following the [Solana Actions specification](https://solana.com/docs/advanced/actions). They eliminate the need to integrate protocol-specific SDKs. For more information about blinks, please see the [Blinks](/blinks) section.

You'll encounter blink URLs in several places:

* **Markets API responses**: In the `actions` object (e.g., `actions.deposit.blinkUrl`)
* **Direct protocol URLs**: Like `https://jupiter.dial.to/api/v0/swap/USDC-SOL`
* **Standard Blinks Library**: A set of curated blinks from top Solana ecosystem projects

On a high level, the process of using blinks is as follows:

<Steps>
  <Step title="GET Request">
    Fetch metadata (title, description, parameters)
  </Step>

  <Step title="POST Request">
    Submit wallet address + parameters → Get transaction
  </Step>

  <Step title="Sign Transaction">
    Sign transaction with wallet → Send to blockchain
  </Step>
</Steps>

## Step 1: Understand Blink Metadata (GET Request)

Blink metadata provides the title, description, icon, and parameters needed to interact with a blink. This information helps you understand the link structure and can be used to build custom UIs (if you don't want to use our [UI components](/blinks/blinks-client/integrate/ui-components/blinks)).

<Tip>
  **Tip:** All SBL blinks include an OpenAPI specification that lets you test them directly in your browser and explore the response structure. You can use these interactive docs instead of fetching metadata manually - jump to [Step 2](#step-2-execute-action-post-request) if you prefer this approach.
</Tip>

### Fetching Metadata Programmatically

If you need to fetch metadata dynamically (e.g., for automation or custom integrations), use the following approach:

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Using Dialect API (recommended for caching and analytics)
  const blinkUrl = 'https://kamino.dial.to/api/v0/lend/HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E/deposit';

  const encodedUrl = encodeURIComponent(blinkUrl);
  const response = await fetch(
    `https://api.dial.to/v1/blink?apiUrl=${encodedUrl}`,
    {
      headers: {
        'X-Blink-Client-Key': 'YOUR_SECRET_TOKEN' 
      }
    }
  );

  const blink = await response.json();
  console.log(blink);
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://kamino.dial.to/api/v0/lend/HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E/deposit' \
    --header 'X-Blink-Client-Key: YOUR_SECRET_TOKEN'
  ```
</CodeGroup>

<Note>
  The `X-Blink-Client-Key` can be requested in our [dashboard](https://dashboard.dialect.to/). See [Request API Keys](/standard-blinks-library/api-keys) for details.
</Note>

### Response Structure

The GET response contains all the information needed to render and interact with the blink:

```json theme={null}
{
  "title": "Deposit USDC in the USDC Prime on Kamino",
  "description": "Deposit USDC into the USDC Prime vault on Kamino Lend and start earning",
  "label": "Deposit",
  "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/81e8dc76-5486-43d6-6dde-6551c563a400/public",
  "links": {
    "actions": [
      {
        "type": "transaction",
        "href": "/api/v0/lend/HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E/deposit?percentage=25",
        "label": "25%"
      },
      {
        "type": "transaction",
        "href": "/api/v0/lend/HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E/deposit?percentage=50",
        "label": "50%"
      },
      {
        "type": "transaction",
        "href": "/api/v0/lend/HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E/deposit?percentage=100",
        "label": "100%"
      },
      {
        "type": "transaction",
        "href": "/api/v0/lend/HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E/deposit?amount={amount}",
        "label": "Deposit",
        "parameters": [
          {
            "name": "amount",
            "type": "number",
            "label": "Enter the amount of USDC you'd like to deposit"
          }
        ]
      }
    ]
  }
}
```

### Understanding Actions

The `links.actions` array contains available operations:

1. **Button actions**: Pre-defined values (25%, 50%, 100%)
   * Use the `href` directly in POST request
   * No additional parameters needed

2. **Parameter actions**: User-provided values (custom amounts)
   * Check `parameters` array for input requirements
   * Replace `{amount}` in `href` with user input (e.g., `?amount=100` for 100 USDC)

## Step 2: Build the POST Request

Once you know which action to execute, submit a POST request with the user's wallet address and the required parameters to return a transaction.

### Percentage Actions

Our example response supports total amounts as well as percentages. For the latter, you can use the `percentage` query parameter. The blink endpoint will automatically fetch the wallet balance and calculate the amount based on the percentage:

<CodeGroup>
  ```typescript TypeScript theme={null}
  // User clicked "25%" button
  const actionHref = 'https://kamino.dial.to/api/v0/lend/HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E/deposit?percentage=25';

  const response = await fetch(actionHref, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Blink-Client-Key': 'YOUR_SECRET_TOKEN'  
    },
    body: JSON.stringify({
      type: 'transaction',
      account: userWalletAddress // User's Solana public key
    })
  });

  const { transaction } = await response.json();
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://kamino.dial.to/api/v0/lend/HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E/deposit?percentage=25' \
    --header 'Content-Type: application/json' \
    --header 'X-Blink-Client-Key: YOUR_SECRET_TOKEN' \
    --data '{
      "type": "transaction",
      "account": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176"
    }'
  ```
</CodeGroup>

### Custom Input Actions

The example response also supports custom input actions, in this case the user can enter the amount of USDC they want to deposit by using the `amount` query parameter:

<CodeGroup>
  ```typescript TypeScript theme={null}
  // User entered custom amount: 100 USDC
  const actionHref = 'https://kamino.dial.to/api/v0/lend/HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E/deposit?amount=1';

  const response = await fetch(actionHref, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Blink-Client-Key': 'YOUR_SECRET_TOKEN'
    },
    body: JSON.stringify({
      type: 'transaction',
      account: userWalletAddress
    })
  });

  const { transaction } = await response.json();
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://kamino.dial.to/api/v0/lend/HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E/deposit?amount=1' \
    --header 'Content-Type: application/json' \
    --header 'X-Blink-Client-Key: YOUR_SECRET_TOKEN' \
    --data '{
      "type": "transaction",
      "account": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176"
    }'
  ```
</CodeGroup>

### POST Response

The response contains a base64-encoded transaction ready for signing:

```json theme={null}
{
  "type": "transaction",
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQAHC07a3stN5LHJrX44cP1FkIaonITAwMLOb6DAY1dBfcLhWPJvNXgJFD8QSviSHc2JxT/h0dFC/yqkDHOxb5VYUMFaGZKRCAwKHlSddxWFAIzGEH4FyLwVVwt7M4L2Np+03fVAdgL/Bv0Dt1KkgYJwGWRNxeCjCtf61qfXk1d3sWh8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP2mzp9mGY3YcNiphvMGdcRvg+L1KDSHlS9dUFY+PvekmQd1hEb77JWicBufx19ba4tsUY8UD0L70PLRzkvX7/jJclj04kifG7PRApFI4NgwtaE5na/xCEBI572Nvp+FnYsBAXY9PlHxJuYVbehd6MYTBZuERo0No/6KKiJRzHAQTZCvHbiTnsNf+U2WQNV9zDJ5S7Phu2b9OuhJqE3NuUC7wPwLtHyi90xBEulKsTz6PGNOXcF+rLA80aI81+eHxzaUNiFAOS2lJOpGMvqjZ3pFwtPaG5kTwosVY/jH43egUHBgABAAsEGAEBCREAEQ0VEwsCARYYGAUJEA8UEhDyI8aJUuHytusJBwAAAAAACAgAAAAAAwwEFwhvEbn6PHom/ggIAAMMDgELCBgQzrDKEsjRs2z//////////woBBgABgunUZsNGfS6ysNnMvrR72/SV7hwbtHfQ2q+tA1+n6+QHBTEvMhMJAQcVBAsCBwYD",
  "dialectExperimental": {
    "reference": "5xAXf6wTbd2BMh76qqg9keqmqtGmU6Gw2GWkpdmaXHTU"
  }
}
```

## Step 3: Sign and Send the Transaction

After receiving the transaction from the POST request, simply sign and send it with your wallet.

```typescript theme={null}
import { Connection, VersionedTransaction } from '@solana/web3.js';

// Deserialize the base64 transaction as it was 
// returned and extracted in the previous step
const transaction = VersionedTransaction.deserialize(
  Buffer.from(transaction, 'base64')
);

// Update blockhash (recommended)
const connection = new Connection('https://api.mainnet-beta.solana.com');
const { blockhash } = await connection.getLatestBlockhash();
transaction.message.recentBlockhash = blockhash;

// Sign and send
const signedTx = await wallet.signTransaction(transaction);
const signature = await connection.sendRawTransaction(signedTx.serialize());

console.log('Transaction successful:', signature);
```

<Warning>
  We recommend to **always update the recent blockhash** before signing. The transaction returned by the API may have an expired blockhash, which will cause the transaction to fail.
</Warning>

### Complete Code Example

Here's a complete example that combines Steps 2 and 3:

```typescript TypeScript theme={null}
import { Connection, VersionedTransaction } from '@solana/web3.js';

async function depositUSDC(wallet, amount: number) {
  try {
    const connection = new Connection('https://api.mainnet-beta.solana.com');
    
    // Step 2: POST request to get transaction
    const response = await fetch(
      `https://kamino.dial.to/api/v0/lend/HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E/deposit?amount=${amount}`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          type: 'transaction',
          account: wallet.publicKey.toString(),
        }),
      }
    );

    const data = await response.json();
    
    // Step 3: Deserialize the transaction
    const transaction = VersionedTransaction.deserialize(
      Buffer.from(data.transaction, 'base64')
    );
    
    // Update blockhash
    const { blockhash } = await connection.getLatestBlockhash();
    transaction.message.recentBlockhash = blockhash;
    
    // Sign and send
    const signedTx = await wallet.signTransaction(transaction);
    const signature = await connection.sendRawTransaction(signedTx.serialize());
    
    console.log('Transaction successful:', signature);
    return signature;
  } catch (error: any) {
    throw new Error(`Deposit failed: ${error.message}`);
  }
}

// Usage
const signature = await depositUSDC(wallet, 100);
console.log('Deposited 100 USDC:', signature);
```

## Advanced Topics

### Multiple Transactions

Some complex operations require multiple sequential transactions. The response will have `type: "transactions"` (plural) with an array:

```json theme={null}
{
  "type": "transactions",
  "transactions": [
    "transaction_1_base64",
    "transaction_2_base64"
  ],
  "mode": "sequential"
}
```

Sign and send each transaction in order, waiting for confirmation before proceeding to the next.

<Note>
  Multiple transactions are experimental and not part of the official Solana Actions spec. See [Handling Multiple Transactions](/blinks/blinks-client/integrate/headless#handling-multiple-transactions-experimental) for details.
</Note>

### Action Chaining

Some blinks support multi-step workflows where one action leads to another. This is useful for complex operations like opening a leveraged position. The response will include a `next` field with the URL for the next step.

Learn more in the [Headless Integration guide](/blinks/blinks-client/integrate/headless#multi-step-blinks-action-chaining).


# Why Use the Standard Blinks Library?
Source: https://docs.dialect.to/standard-blinks-library/why-sbl

Build faster with production-ready APIs. No SDKs, no maintenance burden, just simple HTTP requests.

## Choose Life: APIs Over SDKs

In crypto, we live at dog-year speed. Protocols ship fast, integrations need to be faster. But here's the challenge: every SDK you maintain, every programming language you support, creates a long chain of breaking changes.

**Strong APIs are a win-win**

<CardGroup>
  <Card title="For protocol teams" icon="code">
    Build one great transaction endpoint that works everywhere
  </Card>

  <Card title="For integrators" icon="users">
    Any developer, web2 or web3, can integrate with simple HTTP requests
  </Card>
</CardGroup>

<Info>The best teams are switching to strong APIs instead of maintaining SDKs and the Standard Blinks Library brings this approach to Solana's top protocols.</Info>

<iframe title="Scale or Die Accelerate 2025: Get to Market Faster with Blockchain Links (Bjoern Wagner | Dialect)" />

*Watch the full presentation from Accelerate 2025*

## Why Choose the Standard Blinks Library?

### Quality & Reliability

<CardGroup>
  <Card title="Curated Protocols" icon="star">
    Top Solana ecosystem projects you already know and love
  </Card>

  <Card title="OpenAPI Documentation" icon="book">
    Interactive docs with examples that you can test directly in your browser
  </Card>

  <Card title="Daily Automated Tests" icon="circle-check">
    Tests run across the Standard Blink Library to ensure Blinks remain operational
  </Card>

  <Card title="Production-Ready" icon="shield-check">
    Optimized transactions with validation and error handling built-in
  </Card>

  <Card title="Zero Maintenance" icon="circle-xmark">
    No SDKs to update, no breaking changes, no version conflicts
  </Card>

  <Card title="Regular Updates" icon="arrows-rotate">
    New protocols and operations added weekly
  </Card>
</CardGroup>

### Transactions as a Service

Think of the SBL as **Transactions as a Service**. Instead of:

* Installing heavy SDKs
* Learning protocol-specific APIs
* Managing dependencies across languages
* Dealing with breaking changes

You simply:

* Make an HTTP request
* Receive a ready-to-sign transaction
* Sign it with any wallet

**Every programming language can do this.** Mobile, web, backend. It doesn't matter. If it can make an HTTP request, it can integrate any protocol in the SBL.

## How It Works

<Steps>
  <Step title="Find the Blink">
    Browse the protocol-specific sections in the SBL to find the operation you need (swap, deposit, claim, repay, withdraw, etc.)
  </Step>

  <Step title="Fetch the Transaction">
    Make a simple POST request with the user's wallet address. Get back a ready-to-sign transaction.
  </Step>

  <Step title="Sign and Send">
    Sign the transaction with the user's wallet and send it to Solana. Done.
  </Step>
</Steps>

The only difference between protocols is the URL. Everything else stays the same:

```typescript {2,6} theme={null}
// Define your action - same pattern for any protocol
const swapUsdcToSol = 'https://jupiter.dial.to/api/v0/swap/USDC-SOL/100'
// const borrowSolOnJupiter = 'https://jupiter.dial.to/api/v0/lend/borrow/1/2433/borrow?percentage=90'
// const lendUsdcOnKamino = 'https://kamino.dial.to/api/v0/lend/HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E/deposit?amount=100'

const response = await fetch(swapUsdcToSol, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ account: userWalletAddress })
});

const { transaction } = await response.json();
// That's it. Sign and send.
```

## Ready to Get Started?

<Card title="Quick Start Guide" icon="rocket" href="/standard-blinks-library/quick-start">
  Build your first integration in 5 minutes
</Card>