Skip to content

Commit bbfc05b

Browse files
nidhi-singh02nidhi-singh02
committed
redirect from subscribe updates page
1 parent 6a22df3 commit bbfc05b

File tree

3 files changed

+314
-0
lines changed

3 files changed

+314
-0
lines changed

‎pages/lazer/_meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
"title": "Reference Material",
2626
"type": "separator"
2727
},
28+
"payload-reference": "Payload Reference",
2829
"price-feed-ids": "Price Feed IDs",
2930

3031
"websocket-api-reference": {

‎pages/lazer/payload-reference.mdx‎

Lines changed: 307 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,307 @@
1+
import { Callout, Steps } from "nextra/components";
2+
3+
# Lazer Payload Reference
4+
5+
This page provides a comprehensive reference for understanding Pyth Lazer payload structure, field specifications, and available data formats. This information is essential for integrating with Lazer as a consumer and understanding the data you receive.
6+
7+
<Callout type="info">
8+
This reference is designed for both technical and non-technical stakeholders
9+
to understand Pyth Lazer's data offering. For implementation details, see our
10+
[integration guides](/lazer/integrate-as-consumer).
11+
</Callout>
12+
13+
## What is a Lazer Payload?
14+
15+
A Lazer payload is a real-time data update containing financial market information with cryptographic signatures for verification. When you subscribe to Lazer price feeds, you receive `StreamUpdated` messages containing this structured data.
16+
17+
## Stream Response Structure
18+
19+
When you receive a `StreamUpdated` message from Lazer, it contains the following structure:
20+
21+
### Top-Level Response Fields
22+
23+
| Field | Type | Description |
24+
| ---------------- | --------------- | ------------------------------------------------------ |
25+
| `type` | `string` | Always `"streamUpdated"` for price updates |
26+
| `subscriptionId` | `number` | Your subscription identifier |
27+
| `parsed` | `ParsedPayload` | Human-readable price data (when `parsed: true`) |
28+
| `evm` | `BinaryData` | EVM-compatible binary payload (when requested) |
29+
| `solana` | `BinaryData` | Solana-compatible binary payload (when requested) |
30+
| `leEcdsa` | `BinaryData` | Little-endian ECDSA binary payload (when requested) |
31+
| `leUnsigned` | `BinaryData` | Little-endian unsigned binary payload (when requested) |
32+
33+
### Parsed Payload Structure
34+
35+
The `parsed` object contains human-readable price data:
36+
37+
| Field | Type | Description |
38+
| ------------- | ------------------ | ---------------------------------------------------------- |
39+
| `timestampUs` | `string` | Unix timestamp in microseconds when the data was generated |
40+
| `priceFeeds` | `Array<PriceFeed>` | Array of price feed data objects |
41+
42+
## How Does a Price Feed Look?
43+
44+
Each price feed in the `priceFeeds` array represents real-time market data for a specific trading pair (e.g., BTC/USD, ETH/USD). Think of a price feed as a comprehensive snapshot of market conditions for that asset.
45+
46+
### Example Price Feed Response
47+
48+
Here's what a typical price feed looks like in a Lazer response:
49+
50+
```json
51+
{
52+
"type": "streamUpdated",
53+
"subscriptionId": 1,
54+
"parsed": {
55+
"timestampUs": "1758690761750000",
56+
"priceFeeds": [
57+
{
58+
"priceFeedId": 1,
59+
"price": "11223872331053",
60+
"bestBidPrice": "11222498842767",
61+
"bestAskPrice": "11224513591935",
62+
"publisherCount": 9,
63+
"exponent": -8,
64+
"confidence": 1373488286
65+
}
66+
]
67+
},
68+
"evm": {
69+
"encoding": "base64",
70+
"data": "..."
71+
}
72+
}
73+
```
74+
75+
### Price Feed Structure
76+
77+
Each price feed object contains the following fields:
78+
79+
| Field | Type | Description | Example |
80+
| --------------------- | -------- | ------------------------------------------- | -------------------- |
81+
| `priceFeedId` | `number` | Unique identifier for the price feed | `1` (BTC/USD) |
82+
| `price` | `string` | Main aggregate price (mantissa format) | `"1006900000000"` |
83+
| `exponent` | `string` | Decimal exponent for price conversion | `"-8"` |
84+
| `confidence` | `string` | Price confidence interval (mantissa format) | `"5000000"` |
85+
| `publisherCount` | `string` | Number of data publishers contributing | `"15"` |
86+
| `bestBidPrice` | `string` | Highest bid price across all publishers | `"1006800000000"` |
87+
| `bestAskPrice` | `string` | Lowest ask price across all publishers | `"1007000000000"` |
88+
| `fundingRate` | `string` | Current funding rate for perpetual futures | `"125000"` |
89+
| `fundingTimestamp` | `string` | Timestamp of last funding rate update | `"1730986152000000"` |
90+
| `fundingRateInterval` | `string` | Funding rate update interval (microseconds) | `"28800000000"` |
91+
92+
<Callout type="warning">
93+
**Important**: Price values are in mantissa format. To get the actual price,
94+
use: `actual_price = mantissa × 10^exponent`. For example: `1006900000000 ×
95+
10^(-8) = $10,069.00`
96+
</Callout>
97+
98+
## Property Specifications
99+
100+
Based on the protocol specification, here are the technical details for each property in a price feed:
101+
102+
### Feed Structure
103+
104+
- **Feed ID**: `u32` - Unique identifier for the price feed
105+
- **Properties**: Fields included based on your subscription request parameters
106+
107+
### Core Price Properties
108+
109+
#### Aggregate Market Price - `price`
110+
111+
Main aggregate price calculated from all contributing publishers
112+
113+
- **Type**: `optional non-zero i64` (mantissa representation)
114+
- **Availability**: Only included if requested in subscription properties
115+
- **Algorithm**: Robust statistical aggregation using median-based methods with outlier detection
116+
- **Invariants**: Non-zero when present (null values filtered out)
117+
- **Usage**: Primary price for trading decisions and portfolio valuation
118+
119+
#### Data Publisher Count - `publisher_count`
120+
121+
Number of data publishers contributing to this price feed
122+
123+
- **Type**: `u16`
124+
- **Availability**: Always included when any price properties are present
125+
- **Algorithm**: Count of publishers whose data passed validation and quality checks
126+
- **Invariants**: Always positive for valid price feeds
127+
- **Business Value**: Higher count indicates more robust price discovery and reduced manipulation risk
128+
129+
#### Price Confidence Interval - `confidence`
130+
131+
Confidence interval representing price uncertainty
132+
133+
- **Type**: `optional i64` (mantissa representation)
134+
- **Availability**: Only included if requested in subscription properties
135+
- **Algorithm**: Statistical measure derived from publisher price variance and market volatility
136+
- **Invariants**: Positive when present
137+
- **Usage**: Risk management and price quality assessment
138+
139+
### Market Depth Properties
140+
141+
#### Highest Market Bid - `best_bid_price`
142+
143+
Highest bid price across all contributing publishers
144+
145+
- **Type**: `optional non-zero i64` (mantissa representation)
146+
- **Availability**: Only included if requested in subscription properties
147+
- **Algorithm**: Maximum bid price from all publishers with active order book data
148+
- **Invariants**: Non-zero when present, typically ≤ current price
149+
- **Business Value**: Essential for market makers and algorithmic trading strategies
150+
151+
#### Lowest Market Ask - `best_ask_price`
152+
153+
Lowest ask price across all contributing publishers
154+
155+
- **Type**: `optional non-zero i64` (mantissa representation)
156+
- **Availability**: Only included if requested in subscription properties
157+
- **Algorithm**: Minimum ask price from all publishers with active order book data
158+
- **Invariants**: Non-zero when present, typically ≥ current price
159+
- **Business Value**: Critical for understanding market liquidity and bid-ask spreads
160+
161+
### Derivatives Properties (FundingRate Feed Type Only)
162+
163+
#### Perpetual Futures Funding Rate - `funding_rate`
164+
165+
Current funding rate for perpetual futures contracts
166+
167+
- **Type**: `optional i64` (mantissa representation)
168+
- **Availability**: Only for FeedKind::FundingRate feeds, only if requested in subscription
169+
- **Algorithm**: Interest rate differential: `(PerpetualsPrice - IndexPrice) / IndexPrice`
170+
- **Invariants**: Can be positive (longs pay shorts) or negative (shorts pay longs)
171+
- **Business Value**: Essential for perpetual futures trading and funding arbitrage
172+
173+
#### Funding Payment Timestamp - `funding_timestamp`
174+
175+
Timestamp when funding rate was last calculated or applied
176+
177+
- **Type**: `optional u64` (microseconds)
178+
- **Availability**: Only for FeedKind::FundingRate feeds, only if requested in subscription
179+
- **Invariants**: Valid Unix timestamp in microseconds when present
180+
- **Business Value**: Critical for funding payment timing and schedule management
181+
182+
#### Funding Update Interval - `funding_interval`
183+
184+
Duration between consecutive funding rate calculations
185+
186+
- **Type**: `optional u64` (microseconds)
187+
- **Availability**: Only for FeedKind::FundingRate feeds, only if requested in subscription
188+
- **Invariants**: Positive value when present
189+
- **Typical Values**: 28,800,000,000 microseconds (8 hours) for major exchanges
190+
- **Business Value**: Used for funding cost calculations and payment scheduling
191+
192+
## Available Properties by Use Case
193+
194+
Based on the [API documentation](https://pyth-lazer.dourolabs.app/docs), you can request specific properties when subscribing:
195+
196+
### Common Properties (All Feed Types)
197+
198+
- `publisherCount` - Number of contributing data publishers
199+
- `exponent` - Decimal exponent for proper price representation
200+
201+
### Spot Trading Properties
202+
203+
- `price` - Primary aggregate price for the asset
204+
- `confidence` - Price confidence interval for risk assessment
205+
- `bestBidPrice` - Highest bid across all publishers (market depth)
206+
- `bestAskPrice` - Lowest ask across all publishers (market depth)
207+
208+
### Derivatives Properties
209+
210+
- `fundingRate` - Current funding rate for perpetual futures
211+
- `fundingTimestamp` - Most recent funding rate timestamp
212+
- `fundingRateInterval` - Duration between funding updates
213+
214+
<Callout type="info">
215+
**Subscription Flexibility**: You only receive the properties you request in
216+
your subscription, optimizing bandwidth and processing.
217+
</Callout>
218+
219+
## Subscription Channels
220+
221+
Lazer offers multiple delivery channels to match your latency and frequency requirements:
222+
223+
| Channel | Description | Use Cases |
224+
| ------------------ | --------------------------------------- | ------------------------------------------- |
225+
| `real_time` | Updates sent immediately when available | High-frequency trading, real-time analytics |
226+
| `fixed_rate@1ms` | Updates every 1 millisecond | Ultra-low latency applications |
227+
| `fixed_rate@50ms` | Updates every 50 milliseconds | Low-latency trading systems |
228+
| `fixed_rate@200ms` | Updates every 200 milliseconds | Standard trading applications |
229+
230+
<Callout type="default">
231+
**Channel Selection**: Most production applications use `real_time` for
232+
maximum freshness. Fixed-rate channels provide predictable update timing for
233+
applications requiring consistent intervals.
234+
</Callout>
235+
236+
## Signature Schemes and Binary Formats
237+
238+
Lazer provides multiple cryptographic formats to support different blockchain ecosystems. When you subscribe, you can request specific binary formats in the `chains` parameter:
239+
240+
### Available Formats
241+
242+
| Format | Algorithm | Use Cases | Blockchains |
243+
| ------------ | ---------------------------- | -------------------------- | --------------------------------- |
244+
| `evm` | secp256k1 ECDSA + Keccak-256 | Smart contract integration | Ethereum, BSC, Polygon, Avalanche |
245+
| `solana` | Ed25519 EdDSA | Solana program integration | Solana |
246+
| `leEcdsa` | Little-endian ECDSA | Specialized applications | Custom implementations |
247+
| `leUnsigned` | No signature (testing only) | Off-chain analytics | Testing, development |
248+
249+
### Technical Specifications
250+
251+
<div className="grid grid-cols-1 lg:grid-cols-2 gap-6 mt-6">
252+
253+
<div className="p-6 bg-gray-50 dark:bg-darkGray rounded-lg border border-gray-200 dark:border-gray-700">
254+
#### EVM Format (`evm`)
255+
256+
- **Algorithm**: secp256k1 ECDSA
257+
- **Hash Function**: Keccak-256
258+
- **Signature Size**: 65 bytes
259+
- **Verification**: Recoverable ECDSA with Ethereum address derivation
260+
261+
**Perfect for**: Ethereum smart contracts, DeFi protocols, multi-chain applications
262+
263+
</div>
264+
265+
<div className="p-6 bg-gray-50 dark:bg-darkGray rounded-lg border border-gray-200 dark:border-gray-700">
266+
#### Solana Format (`solana`)
267+
268+
- **Algorithm**: Ed25519 EdDSA
269+
- **Signature Size**: 64 bytes
270+
- **Public Key Size**: 32 bytes
271+
- **Verification**: Direct Ed25519 signature verification
272+
273+
**Perfect for**: Solana programs, high-performance applications
274+
275+
</div>
276+
277+
<div className="p-6 bg-gray-50 dark:bg-darkGray rounded-lg border border-gray-200 dark:border-gray-700">
278+
#### Little-Endian ECDSA (`leEcdsa`)
279+
280+
- **Algorithm**: secp256k1 ECDSA (little-endian)
281+
- **Hash Function**: Keccak-256
282+
- **Byte Order**: Little-endian encoding
283+
284+
**Perfect for**: Custom implementations requiring specific byte ordering
285+
286+
</div>
287+
288+
<div className="p-6 bg-gray-50 dark:bg-darkGray rounded-lg border border-gray-200 dark:border-gray-700">
289+
#### Unsigned Format (`leUnsigned`)
290+
291+
- **Signature**: None (raw payload)
292+
- **Use Cases**: Testing, development, trusted environments
293+
294+
<Callout type="warning">
295+
**Security Warning**: Never use in production
296+
297+
</Callout>
298+
299+
</div>
300+
301+
</div>
302+
303+
<Callout type="info">
304+
**How to Choose**: Use `evm` for Ethereum-compatible chains, `solana` for
305+
Solana, `leEcdsa` for custom implementations, and `leUnsigned` only for
306+
testing.
307+
</Callout>

‎pages/lazer/subscribe-price-updates.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,12 @@ Determine the most suitable values for your application -- they will be used in
5151

5252
### 3. Subscribe to the price updates
5353

54+
<Callout type="info">
55+
**Complete Payload Reference**: For understanding all fields and data types of
56+
Lazer payloads, see our [**Payload Reference**](/lazer/payload-reference)
57+
page.
58+
</Callout>
59+
5460
To subscribe to the price updates, send a request to the websocket server. The server will respond with a signed price update.
5561

5662
1. Pyth Lazer provides an [SDK](https://github.com/pyth-network/pyth-crosschain/tree/main/lazer/sdk/js) to seamlessly integrate the websocket API into your application.

0 commit comments

Comments
 (0)