# Surge Price Feeds

> **Version source of truth:** [SDK Version Matrix](https://docs.switchboard.xyz/tooling/sdk-version-matrix)

## The Future of Oracle Technology

Switchboard Surge is the industry's fastest oracle data delivery system, providing sub-100ms latency through direct WebSocket streaming. Built for the next generation of DeFi applications, trading systems, and real-time dashboards.

## Key Innovation

Traditional oracles require multiple steps—gathering prices, writing to blockchain state, reaching consensus, and then making data available—resulting in 2-10 seconds of latency.

Switchboard oracles must pass a hardware proof when joining the network, ensuring they run only verified Switchboard code. This allows oracles to stream price data directly from sources to your application via WebSocket, achieving sub-100ms latency.

```
┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Price Sources   │────▶│  Oracle Network  │────▶│  Surge Gateway   │
│   (CEX, DEX)     │     │ (SAIL Verified)  │     │   (WebSocket)    │
└──────────────────┘     └──────────────────┘     └────────┬─────────┘
                                                          │
                                               ┌──────────▼──────────┐
                                               │   Your Application  │
                                               │  • Event Listeners  │
                                               │  • Price Handlers   │
                                               │  • Oracle Quotes    │
                                               └─────────────────────┘
```

## Key Features

**Unmatched Performance** — Sub-100ms latency with direct WebSocket streaming and event-driven updates. No polling required.

**Zero Setup** — No data feed accounts, on-chain deployment, or SOL funding needed. Just use your keypair and connection to start streaming.

**Cost Efficiency** — Subscription-based pricing with no gas fees for receiving updates. Reduced on-chain costs when converting to Oracle Quotes.

**Seamless Integration** — TypeScript/JavaScript SDK, WebSocket API for any language, and Oracle Quote conversion for on-chain use.

**Enterprise-Grade Reliability** — 99.9% uptime SLA with global infrastructure, automatic failover, and professional support.

## User Flow

Surge works the same way regardless of your target chain:

1. **Subscribe** — All Surge subscriptions are managed on Solana, regardless of which chain you're building on. Connect your Solana wallet at the [subscription portal](https://explorer.switchboardlabs.xyz/subscriptions).
2. **Authenticate** — The SDK authenticates your session by signing with your Solana keypair. If the keypair does not have an active subscription, `connectAndSubscribe` will fail.
3. **Stream Prices** — Once subscribed, prices stream directly to your application via WebSocket. No on-chain reads required—this is what enables sub-100ms latency.
4. **Use Prices** — When you need prices on-chain, convert the Surge update to your chain's format and submit it. Switchboard provides SDKs for Solana, EVM, and Sui.

## Getting Started

### 1. Subscribe

Connect your wallet and subscribe at [explorer.switchboardlabs.xyz/subscriptions](https://explorer.switchboardlabs.xyz/subscriptions). If you are an AI agent or wish to subscribe programmatically rather than through the UI, see the [Surge Subscription Guide](https://docs.switchboard.xyz/ai-agents-llms/surge-subscription-guide).

### 2. Install the SDK

```bash
npm install @switchboard-xyz/on-demand@3.9.0
# or
yarn add @switchboard-xyz/on-demand@3.9.0
```

### 3. Connect and Stream

```typescript
import * as sb from "@switchboard-xyz/on-demand";

// Initialize with keypair and connection (uses on-chain subscription)
const surge = new sb.Surge({ connection, keypair });
// `connection` is a Solana RPC Connection from @solana/web3.js.

// Discover available feeds
const availableFeeds = await surge.getSurgeFeeds();
console.log(`${availableFeeds.length} feeds available`);

// Subscribe to specific feeds
await surge.connectAndSubscribe([
  { symbol: 'BTC/USD' },
  { symbol: 'ETH/USD' },
  { symbol: 'SOL/USD' }
]);

// Handle price updates
surge.on('signedPriceUpdate', (response: sb.SurgeUpdate) => {
  const metrics = response.getLatencyMetrics();
  if (metrics.isHeartbeat) return;

  const prices = response.getFormattedPrices();
  metrics.perFeedMetrics.forEach((feed) => {
    console.log(`${feed.symbol}: ${prices[feed.feed_hash]}`);
  });
});
```

## Pricing & Limits

| Plan           | Price       | Quote Interval | Max Feeds | Max Connections |
| -------------- | ----------- | -------------- | --------- | --------------- |
| **Plug**       | Free        | 10s            | 2         | 1               |
| **Pro**        | \~$3,000/mo | 450ms          | 100       | 10              |
| **Enterprise** | \~$7,500/mo | 0ms            | 300       | 15              |

Subscriptions are paid in SWTCH tokens. For custom limits or dedicated support, contact <sales@switchboard.xyz>.

## Primary Use Cases

### Perpetual Exchanges

Surge is the perfect oracle solution for perpetual trading platforms:

```typescript
surge.on('signedPriceUpdate', async (response: sb.SurgeUpdate) => {
  const metrics = response.getLatencyMetrics();
  if (metrics.isHeartbeat) return;

  const prices = response.getFormattedPrices();

  for (const feed of metrics.perFeedMetrics) {
    const price = parseFloat(prices[feed.feed_hash].replace(/[$,]/g, ''));
    const market = this.markets.get(feed.symbol);

    // Update mark price instantly
    market.oraclePrice = price;

    // Trigger liquidations if needed
    const underwaterPositions = await this.findUnderwaterPositions(market);
    for (const position of underwaterPositions) {
      if (this.isLiquidatable(position, market.oraclePrice)) {
        const crankIxs = response.toQuoteIx(queue.pubkey, keypair.publicKey);
        await this.liquidatePosition(position, crankIxs);
      }
    }
  }
});
```

### Oracle-Based AMMs

Build the next generation of AMMs that use real-time oracle prices:

```typescript
class OracleAMM {
  private latestUpdate: sb.SurgeUpdate;

  constructor(private surge: sb.Surge) {
    surge.on('signedPriceUpdate', this.handlePriceUpdate.bind(this));
  }

  async handlePriceUpdate(response: sb.SurgeUpdate) {
    const metrics = response.getLatencyMetrics();
    if (metrics.isHeartbeat) return;

    this.latestUpdate = response;
    const prices = response.getFormattedPrices();

    for (const feed of metrics.perFeedMetrics) {
      const pair = this.pairs.get(feed.symbol);
      pair.oraclePrice = parseFloat(prices[feed.feed_hash].replace(/[$,]/g, ''));
      pair.lastUpdate = Date.now();
    }
  }

  async executeSwap(tokenIn: string, tokenOut: string, amountIn: number) {
    const pair = `${tokenIn}/${tokenOut}`;
    const latestPrice = this.pairs.get(pair).oraclePrice;
    const amountOut = amountIn * latestPrice * (1 - this.swapFee);

    // Convert to Oracle Quote for on-chain execution
    const crankIxs = this.latestUpdate.toQuoteIx(queue.pubkey, keypair.publicKey);

    return await this.program.methods
      .swap(amountIn, amountOut)
      .accounts({ amm: this.ammPda, queue: this.queuePubkey })
      .preInstructions(crankIxs)
      .rpc();
  }
}
```

### High-Frequency Trading & Arbitrage

```typescript
surge.on('signedPriceUpdate', async (response: sb.SurgeUpdate) => {
  const metrics = response.getLatencyMetrics();
  if (metrics.isHeartbeat) return;

  const prices = response.getFormattedPrices();

  for (const feed of metrics.perFeedMetrics) {
    const oraclePrice = parseFloat(prices[feed.feed_hash].replace(/[$,]/g, ''));
    const dexPrice = await getDexPrice(feed.symbol);

    const spread = Math.abs(dexPrice - oraclePrice) / oraclePrice;
    if (spread > MIN_PROFIT_THRESHOLD) {
      const crankIxs = response.toQuoteIx(queue.pubkey, keypair.publicKey);
      await executeArbitrage(crankIxs, calculateOptimalSize(spread));
    }
  }
});
```

### Liquidation Engines

```typescript
surge.on('signedPriceUpdate', async (response: sb.SurgeUpdate) => {
  const metrics = response.getLatencyMetrics();
  if (metrics.isHeartbeat) return;

  const prices = response.getFormattedPrices();

  for (const feed of metrics.perFeedMetrics) {
    const price = parseFloat(prices[feed.feed_hash].replace(/[$,]/g, ''));
    const positions = await getPositionsByCollateral(feed.symbol);

    for (const position of positions) {
      const ltv = calculateLTV(position, price);
      if (ltv > LIQUIDATION_THRESHOLD) {
        const crankIxs = response.toQuoteIx(queue.pubkey, keypair.publicKey);
        await liquidatePosition(position, crankIxs);
      }
    }
  }
});
```

## Technical Specifications

### Program ID

```
orac1eFjzWL5R3RbbdMV68K9H6TaCVVcL6LjvQQWAbz
```

### Latency Breakdown

* Oracle processing: \~10ms
* Network transmission: \~20-50ms
* Client processing: \~10ms
* **Total: <100ms**

### Discovering Available Feeds

Use the `getSurgeFeeds()` method to see all available trading pairs:

```typescript
const surge = new sb.Surge({ connection, keypair });
// `connection` is a Solana RPC Connection from @solana/web3.js.
const feeds = await surge.getSurgeFeeds();

feeds.forEach(feed => {
  console.log(`${feed.symbol}`);
});
```

### Supported Assets

* All major cryptocurrency pairs
* Multiple exchange sources available
* New pairs added regularly
* Custom feeds available on request

Note: Surge does not support custom feeds created with the [feed builder](https://explorer.switchboardlabs.xyz/feed-builder).

## FAQ

### How is Surge different from traditional oracles?

Surge streams data directly to your application via WebSocket, bypassing the blockchain entirely for reads. This eliminates gas costs and reduces latency from seconds to milliseconds.

### Can I use Surge data on-chain?

Yes! Surge updates can be converted to Oracle Quote format for on-chain use: `response.toQuoteIx(queue.pubkey, keypair.publicKey)`

### What's the reliability?

Surge operates with 99.9% uptime SLA, automatic failover, and global redundancy. Enterprise customers get dedicated infrastructure.

### How do I handle disconnections?

The SDK includes automatic reconnection logic with exponential backoff. Your application will seamlessly recover from network interruptions.

## Next Steps

* [Surge Tutorial](https://github.com/switchboard-xyz/gitbook-on-demand/blob/main/docs-by-chain/solana-svm/surge/surge.md) - Step-by-step implementation guide
* [Crossbar Gateway](https://docs.switchboard.xyz/tooling/crossbar) - Stream prices to your frontend
* [Surge Gateway Protocol](https://docs.switchboard.xyz/tooling/crossbar/gateway-protocol) - Advanced HTTP + WebSocket protocol
* [Explore code examples](https://github.com/switchboard-xyz/sb-on-demand-examples)
* [Join our Discord](https://discord.gg/TJAv6ZYvPC)