Skip to main content
Pyth
Every price-sensitive operation in Kimia reads a Pyth Hermes Pull Oracle.
Pull oracles are fundamentally different from the old “push” model: the PriceUpdateV2 account lands on-chain in the same transaction that uses it.

​
The flow

1

Off-chain: fetch a signed update

const res = await fetch(
  `https://hermes.pyth.network/v2/updates/price/latest?ids[]=${FEED_ID}`
);
const { binary } = await res.json();
2

Build a postPriceUpdate instruction

import { PythSolanaReceiver } from '@pythnetwork/pyth-solana-receiver';
const tx = await receiver.buildPostPriceUpdateInstructions(binary.data);
3

Prepend it to your Kimia instruction

The resulting price_update account becomes the oracle argument to place_order, liquidate, update_funding_rate, etc.
4

Atomic consumption

Post + consume happen in the same tx. No window for staleness. No chance of a front-run replacing the price you expected.

​
On-chain validation

Kimia’s perps-common::validate_pyth_oracle enforces five checks before any price is used:
CheckWhat
OwnerAccount owner must be the Pyth Receiver program (rec5EKMGg7MpqG6xfy3DaFUkbNvVz4vDRNPn1fPqMoh).
DeserializationAccount must decode as PriceUpdateV2.
Feed IDMust match the market’s configured oracle account’s feed.
Stalenesspublish_time within oracle_staleness_threshold (default 60s) of chain clock.
Confidenceconfidence / price × 10_000 ≤ oracle_confidence_max_bps (default 250 bps = 2.5%).
Any failure short-circuits the instruction with a clear error code (6000..6002).

​
Normalization

Pyth feeds typically report with expo = -8 (eight decimals). Kimia normalizes to six decimals internally: target_price=pyth_price×10pyth_expo−target_expo106\text{target\_price} = \frac{\text{pyth\_price} \times 10^{\text{pyth\_expo} - \text{target\_expo}}}{10^6} Example: SOL at 130.00000000 (pyth_price = 13_000_000_000, expo = -8) becomes 130_000_000 at expo = -6.

​
Where oracles are used

ProgramInstructionPurpose
kimia-perpplace_orderMargin and slippage checks
kimia-perpliquidateClose price
kimia-perpupdate_funding_rateOracle TWAP update
kimia-perpspot_swapSwap price
delta-vaultrebalanceGap detection

Perpetuals

Where oracle reads feed into margin and liquidation.

Error codes

Oracle error codes and how to handle them.