> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainworks.org/llms.txt
> Use this file to discover all available pages before exploring further.

# SVM Price Subscriptions

> Subscribe to real-time Solana token price updates over the WebSocket connection.

Subscribe to real-time price updates for Solana tokens. When a subscribed token's price changes, you receive a `priceUpdate` event on your Socket.IO connection with the latest price from the highest-liquidity pool.

> **Live updates are Socket.IO only.** You can manage subscriptions (subscribe, unsubscribe, list active) over either transport, but `priceUpdate` and `subscriptionExpiring` events are pushed only over a Socket.IO connection. Over HTTP, the subscribe/unsubscribe/active endpoints just register and query subscriptions; they do not deliver price updates. To receive live prices you must be connected via Socket.IO.

***

## Subscription Limits

Maximum active subscriptions per tier:

| Tier | Max Subscriptions |
| - | - |
| Free | 0 |
| Basic | 10 |
| Premium | 100 |
| Enterprise | 1,000 |

***

## Subscribe

Subscribe to price updates for one or more tokens.

**Endpoint:** `/svm/price/subscribe`

| Parameter | Type | Required | Description |
| - | - | - | - |
| `chain` | string | Yes | Always `sol` |
| `tokens` | string\[] | Yes | Array of token mint addresses (min 1) |
| `ttlMs` | number | No | Subscription duration in milliseconds. Max: 604,800,000 (7d), default: 21,600,000 (6h) |

**Example:**

> [tab] Socket.IO
>
> ```typescript theme={null}
> socket.emit("/svm/price/subscribe", {
>   chain: "sol",
>   tokens: [
>     "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
>     "So11111111111111111111111111111111111111112",
>   ],
>   ttlMs: 21600000, // 6 hours
> });
> ```

> [tab] HTTP
>
> ```typescript theme={null}
> await fetch("https://api.chainworks.co/svm/price/subscribe", {
>   method: "POST",
>   headers: {
>     "Content-Type": "application/json",
>     Authorization: CHAINWORKS_API_AUTH_TOKEN,
>   },
>   body: JSON.stringify({
>     chain: "sol",
>     tokens: [
>       "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
>       "So11111111111111111111111111111111111111112",
>     ],
>     ttlMs: 21600000, // 6 hours
>   }),
> });
> ```

**Response:**

```json theme={null}
{
  "success": true,
  "result": {
    "subscribed": [
      "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "So11111111111111111111111111111111111111112"
    ]
  }
}
```

Re-subscribing to an already-subscribed token refreshes its TTL without counting against the subscription limit.

***

## Unsubscribe

Unsubscribe from price updates for one or more tokens.

**Endpoint:** `/svm/price/unsubscribe`

| Parameter | Type | Required | Description |
| - | - | - | - |
| `chain` | string | Yes | Always `sol` |
| `tokens` | string\[] | Yes | Array of token mint addresses to unsubscribe |

**Example:**

> [tab] Socket.IO
>
> ```typescript theme={null}
> socket.emit("/svm/price/unsubscribe", {
>   chain: "sol",
>   tokens: ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"],
> });
> ```

> [tab] HTTP
>
> ```typescript theme={null}
> await fetch("https://api.chainworks.co/svm/price/unsubscribe", {
>   method: "POST",
>   headers: {
>     "Content-Type": "application/json",
>     Authorization: CHAINWORKS_API_AUTH_TOKEN,
>   },
>   body: JSON.stringify({
>     chain: "sol",
>     tokens: ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"],
>   }),
> });
> ```

**Response:**

```json theme={null}
{
  "success": true,
  "result": {
    "unsubscribed": ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"]
  }
}
```

***

## Active Subscriptions

List all active (non-expired) price subscriptions.

**Endpoint:** `/svm/price/active_subscriptions`

| Parameter | Type | Required | Description |
| - | - | - | - |
| `chain` | string | Yes | Always `sol` |

**Example:**

> [tab] Socket.IO
>
> ```typescript theme={null}
> socket.emit("/svm/price/active_subscriptions", {
>   chain: "sol",
> });
> ```

> [tab] HTTP
>
> ```typescript theme={null}
> await fetch("https://api.chainworks.co/svm/price/active_subscriptions", {
>   method: "POST",
>   headers: {
>     "Content-Type": "application/json",
>     Authorization: CHAINWORKS_API_AUTH_TOKEN,
>   },
>   body: JSON.stringify({
>     chain: "sol",
>   }),
> });
> ```

**Response:**

```json theme={null}
{
  "success": true,
  "result": {
    "tokens": [
      "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "So11111111111111111111111111111111111111112"
    ]
  }
}
```

***

## Price Update Event

When a subscribed token's price changes, you receive a `priceUpdate` event. Updates are sourced from the highest-liquidity pool for the token and deduplicated so you only receive meaningful price changes.

```typescript theme={null}
socket.on("priceUpdate", (data) => {
  console.log(data);
});
```

**Event payload:**

```json theme={null}
{
  "chain": "sol",
  "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "pool": {
    "type": "RaydiumV4",
    "lp": "58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2",
    "backingToken": "So11111111111111111111111111111111111111112",
    "rawPrice": 0.000034,
    "priceUsd": 0.0051,
    "tokenReserve": "1000000000000",
    "backingReserve": "34000000"
  },
  "slotNumber": 285000000,
  "timestamp": 1710979200
}
```

| Field | Type | Description |
| - | - | - |
| `chain` | string | Always `sol` |
| `token` | string | Token mint address |
| `pool.type` | string | DEX type (e.g. `RaydiumV4`, `PumpSwap`, `MeteoraDLMM`) |
| `pool.lp` | string | Liquidity pool address |
| `pool.backingToken` | string | Backing token mint (e.g. SOL or USDC) |
| `pool.rawPrice` | number | Raw price ratio (token lamports / backing lamports) |
| `pool.priceUsd` | number | Price of 1 full token in USD |
| `pool.tokenReserve` | string | Token reserve amount in the pool |
| `pool.backingReserve` | string | Backing token reserve amount in the pool |
| `slotNumber` | number | Solana slot number of the update |
| `timestamp` | number | Unix timestamp in seconds |

***

## Subscription Expiring Event

You receive a `subscriptionExpiring` event shortly before a subscription expires, and again when it actually expires. Use this to re-subscribe if needed.

```typescript theme={null}
socket.on("subscriptionExpiring", (data) => {
  console.log(data);
});
```

**Event payload:**

```json theme={null}
{
  "chain": "sol",
  "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "expiresAt": 1711065600,
  "expired": false
}
```

| Field | Type | Description |
| - | - | - |
| `chain` | string | Always `sol` |
| `token` | string | Token mint address |
| `expiresAt` | number | Unix timestamp (seconds) when the subscription expires |
| `expired` | boolean | `false` when expiring soon, `true` when already expired |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.