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

# onPriceUpdated

> Live-streamed price updates for a token. Reference for the onPriceUpdated subscription in the Codex API: arguments, payload fields, and usage.

<div data-generated>
  ## GraphQL

  ```
  type Subscription {
    # Requires a Growth or Enterprise plan.
    onPriceUpdated(
      address: String
      networkId: Int
      sourcePairAddress: String
      useWeightedPrices: Boolean
    ): Price
  }

  type Price {
    address: String!
    timestamp: Int
    networkId: Int!
    priceUsd: Float!
    blockNumber: Int
    liquidityUsd: String
    priceChange24: Float
  }
  ```
</div>

### Example

<a href="/explore" target="_blank" rel="noopener noreferrer">Test this query in the Explorer →</a>

```graphql theme={null}
subscription {
  onPriceUpdated(
    address: "So11111111111111111111111111111111111111112"
    networkId: 1399811149
  ) {
    address
    networkId
    priceUsd
    timestamp
    blockNumber
  }
}
```

```json Example Response theme={null}
{
  "data": {
    "onPriceUpdated": {
      "address": "So11111111111111111111111111111111111111112",
      "networkId": 1399811149,
      "priceUsd": 126.7659247882934,
      "timestamp": 1769559478,
      "blockNumber": 396371407
    }
  }
}
```

<Note>
  **Network-wide price streams**: `onPriceUpdated` can also stream **every price update across an entire network**. This capability isn't part of standard plans — it's a dedicated add-on billed at a flat monthly rate per network rather than per request, with package discounts when you subscribe to more than one network, and it must be enabled before use. The PriceFeed entitlement is attached to **specific API keys**, not to your account as a whole: a key without it still requires `address`, and if you need the stream on more than one key, ask us to enable each key. Currently available on Solana, BNB, Base, Robinhood, and more. Contact us at [hello@codex.io](mailto:hello@codex.io?subject=Network-wide%20Price%20Updates) or on [Telegram](https://t.me/CodexData) to get set up.
</Note>

### Usage Guidelines

* Provide `address` (token contract address) and `networkId` to subscribe to price updates for a specific token
* `priceUsd` returns the current USD price of the token, updated at most once per block — you receive a single price per token per block
* Optionally specify `sourcePairAddress` to get pricing from a specific liquidity pool instead of the default top pair
* Use `blockNumber` to track which block the price update originated from
* This subscription is ideal for simple price feeds — use `onBarsUpdated` if you need OHLCV candlestick data

### Troubleshooting Tips

<AccordionGroup>
  <Accordion title="How is the price determined?">
    By default, the price is derived from the token's top liquidity pair. You can override this by passing a `sourcePairAddress` to use a specific pool for pricing.
  </Accordion>

  <Accordion title="How often are updates sent?">
    Updates are sent in real-time as new blocks land, at most once per token per block. If a token trades multiple times within a single block, you receive only its most recent price for that block rather than one update per swap. Tokens that trade across more blocks produce more frequent updates.
  </Accordion>

  <Accordion title="When should I use onPriceUpdated vs onBarsUpdated?">
    Use `onPriceUpdated` for a simple, real-time price feed (e.g., displaying a live price ticker). Use `onBarsUpdated` when you need OHLCV candlestick data, volume breakdowns, or multiple time resolutions for charting.
  </Accordion>

  <Accordion title="What about the poolAddress and confidence fields?">
    These fields are deprecated. Pricing is no longer based on specific pools, so these values are no longer meaningful. Use `blockNumber` instead to track the source of price updates.
  </Accordion>
</AccordionGroup>


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