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

# Starkex

> Real-time price data with cryptographic verification for StarkEx integrations

<Card title="Verified Price Feeds" icon="shield-check">
  Perfect for StarkEx integrations and applications requiring cryptographic verification of price data
</Card>

## Overview

If you are building on [StarkEx](https://starkware.co/starkex/) or need a robust verification mechanism for price data, this endpoint provides real-time feeds with cryptographic signatures to ensure data integrity and provenance.

## Connection

<Steps>
  <Step title="Open WebSocket Connection">
    Connect to our WebSocket endpoint on your preferred environment:

    <CodeGroup>
      ```bash Development theme={null}
      wscat -c wss://ws.devnet.pragma.build/node/v1/data/subscribe
      ```

      ```bash Production theme={null}
      wscat -c wss://ws.production.pragma.build/node/v1/data/subscribe
      ```
    </CodeGroup>
  </Step>

  <Step title="Subscribe to Asset Pairs">
    Send a subscription message to start receiving updates every 500 milliseconds.
  </Step>
</Steps>

## Subscription Management

### Subscribing to Pairs

<CodeGroup>
  ```json Request theme={null}
  {
    "msg_type": "subscribe",
    "pairs": ["BTC/USD", "ETH/USD:MARK"]
  }
  ```

  ```json Response theme={null}
  {
    "msg_type": "subscribe",
    "pairs": ["BTC/USD", "ETH/USD:MARK", "SOL/USD"]
  }
  ```
</CodeGroup>

<Note>
  The response includes all pairs you are currently subscribed to, including any previous subscriptions not mentioned in your latest request.
</Note>

### Unsubscribing from Pairs

<CodeGroup>
  ```json Request theme={null}
  {
    "msg_type": "unsubscribe",
    "pairs": ["BTC/USD"]
  }
  ```

  ```json Response theme={null}
  {
    "msg_type": "unsubscribe",
    "pairs": ["ETH/USD:MARK"]
  }
  ```
</CodeGroup>

## Price Types

<Tabs>
  <Tab title="Index Price">
    <Card>
      <p>Median price from spot markets across supported exchanges.</p>
      <p className="font-semibold mt-2">Format Example: <code>BTC/USD</code></p>
    </Card>

    <Note>
      By default, subscriptions are for index prices. Subscribing to a pair without specifying the type will subscribe to the index price.
    </Note>
  </Tab>

  <Tab title="Mark Price">
    <Card>
      <p>Median price from perpetual markets across supported exchanges.</p>
      <p className="font-semibold mt-2">Format Example: <code>ETH/USD:MARK</code></p>
    </Card>

    <div className="mt-4">
      <p className="font-semibold">Calculation Method:</p>

      <p className="mt-2">For assets quoted in a stablecoin:</p>

      <ol className="list-decimal pl-5 mt-1">
        <li>Determine the median perp price of the asset quoted in the stablecoin</li>
        <li>Determine the median spot price of the stablecoin in USD</li>
        <li>Divide the median perp price by the median spot price of the stablecoin in USD</li>
      </ol>

      <p className="mt-2">For assets quoted in USD:</p>

      <ul className="list-disc pl-5 mt-1">
        <li>Determine the median perp price of the asset quoted in USD</li>
      </ul>
    </div>

    <Note>
      To subscribe to a mark price, append <code>:MARK</code> to the pair name (e.g., <code>ETH/USD:MARK</code>).
    </Note>
  </Tab>
</Tabs>

## Data Format

<CodeGroup>
  ```json Example Price Update theme={null}
  {
    "global_asset_id": "0x12345",
    "median_price": "10000000000000001",
    "signature": "0x154786876ae878",
    "signed_prices": [
      {
        "oracle_asset_id": "0x12345000000000ABCDEF",
        "oracle_price": "1000000000000000000",
        "signing_key": "0x1234567890ABCDEF",
        "timestamp": "1234567",
        "signature": "0x1234567890ABCDEF"
      },
      {
        "oracle_asset_id": "0x12345000000000FEDCBA",
        "oracle_price": "1000000000000000002",
        "signing_key": "0xFEDCBA0987654321",
        "timestamp": "1234567",
        "signature": "0x1234567890ABCDEF"
      }
    ]
  }
  ```
</CodeGroup>

### Field Reference

| Field             | Description                                                  |
| ----------------- | ------------------------------------------------------------ |
| `global_asset_id` | Unique identifier for the asset encoded using the pair name  |
| `median_price`    | The median price of the asset                                |
| `signature`       | Signature of the median price by the Pragma oracle           |
| `signed_prices`   | Array of the prices used to compute the median price         |
| `oracle_asset_id` | Unique identifier encoded using the pair and publisher names |
| `oracle_price`    | Price provided by the oracle                                 |
| `signing_key`     | Key used by the oracle to sign the price                     |
| `timestamp`       | Time when the price was recorded                             |
| `signature`       | Signature of the price by our publisher                      |

<Info>
  All numeric values are returned as strings to preserve precision, especially for assets with very small or very large prices.
</Info>

## Integration Examples

<Tabs>
  <Tab title="Rust">
    <div className="mb-4">
      We've created a ready-to-use example with a terminal UI for testing this endpoint:
    </div>

    <CodeGroup>
      ```bash theme={null}
      # Clone the repository
      git clone https://github.com/astraly-labs/pragma-node

      # Run the example
      cargo run --example starkex
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Python">
    <div className="mb-4">
      Connect to the Pragma websocket endpoint and subscribe to the TIA/USD index price:
    </div>

    <CodeGroup>
      ```python theme={null}
      import asyncio
      import websockets
      import json
      from websockets.exceptions import ConnectionClosedError

      async def connect_and_subscribe():
          uri = "wss://ws.devnet.pragma.build/node/v1/data/subscribe"
          
          try:
              # Connect to the websocket
              async with websockets.connect(uri) as websocket:
                  # Subscribe to TIA/USD price
                  subscribe_msg = {
                      "msg_type": "subscribe", 
                      "pairs": ["TIA/USD"]
                  }
                  
                  await websocket.send(json.dumps(subscribe_msg))
                  print("Subscribed to TIA/USD")
                  
                  # Handle incoming messages
                  while True:
                      message = await websocket.recv()
                      data = json.loads(message)
                      print(f"Received price update: {data}")
                      
          except ConnectionClosedError:
              print("Connection closed unexpectedly")
          except Exception as e:
              print(f"Error: {e}")

      # Run the connection
      if __name__ == "__main__":
          asyncio.run(connect_and_subscribe())
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Comparison with Lightspeed

<CardGroup cols={2}>
  <Card title="Starkex" icon="shield-check">
    <ul className="list-none space-y-2 mt-2">
      <li>✓ Includes cryptographic signatures</li>
      <li>✓ Verifiable price data</li>
      <li>✓ Individual publisher prices</li>
      <li>✓ Ideal for StarkEx integration</li>
      <li>⚠️ Slightly larger payload size</li>
    </ul>
  </Card>

  <Card title="Lightspeed" icon="bolt">
    <ul className="list-none space-y-2 mt-2">
      <li>✓ Minimal payload size</li>
      <li>✓ Optimized for performance</li>
      <li>✓ Lower latency</li>
      <li>✓ Ideal for trading applications</li>
      <li>❌ No verification metadata</li>
    </ul>
  </Card>
</CardGroup>

<Tip>
  Choose Starkex when data provenance and verification are required, and Lightspeed when raw performance is your primary concern.
</Tip>