/pyth-oracle

name: pyth-oracle
description: Integrate Pyth oracle prices into a Sui Move package. Use when the user mentions Pyth or wants price oracles on Sui.

Preamble (run first)

# Suiperpower telemetry. Routes through the CLI so projects.json + Convex stay in sync.
# Silent on failure so the skill never blocks. Opt out: SUIPERPOWER_TELEMETRY=off.
#
# AGENT NOTE: when this skill finishes, run the matching completion command:
#   suiperpower track pyth-oracle build completed
# Or use "failed" / "aborted" if it ended that way.
command -v suiperpower >/dev/null 2>&1 && suiperpower track pyth-oracle build started >/dev/null 2>&1 &
true

If `TEL_PROMPTED` is `no`, before doing real work, ask the user:

> Help suiperpower get better. We track which skills get used and how long they take. No code, no file paths, no PII. Change anytime in `~/.suiperpower/config.json`. > > A) Sure, anonymous > B) No thanks

Write the answer to `~/.suiperpower/config.json` `telemetryTier` field and create `~/.suiperpower/.telemetry-prompted`. Then continue.

What this skill does

Integrates Pyth pull-based price feeds into a Sui project so the user's Move contract can read real-time, signed prices for 1500+ assets. Walks the user through the Move dependency, TS client setup, on-chain price consumption, and verifies a real price read on testnet before declaring done.

When to use it

• The project needs real-time token or asset prices on chain (DeFi, lending, perps, liquidations).
• The user wants to integrate Pyth price feeds into a Move contract.
• The user is building a protocol that requires oracle data (collateral valuation, settlement, trigger conditions).
• The user is targeting a DeFi-related track at Sui Overflow 2026 and needs price data.

When NOT to use it

• If the user has not picked a project yet, use `find-next-sui-idea` first.
• If the user has not scaffolded a project, use `scaffold-project` first.
• If the user needs to write general Move code (not oracle-specific), use `build-with-move`.
• If the user wants to build a DEX orderbook, use `deepbook-orderbook`.
• If the user wants lending/borrowing integration, use `scallop-money-market` (which may itself use Pyth internally).

If you activated this and the user actually wants something else, consult `skills/SKILL_ROUTER.md` and hand off.

Inputs

• A Sui project (Move package and/or TS frontend).
• Optional: `.suiperpower/build-context.md` from `scaffold-project`. Read it if present.
• The asset(s) the user needs prices for.

If unclear, interview the user for:

• Which asset prices? (SUI/USD, BTC/USD, a custom pair?)
• What staleness tolerance? (seconds, default 60)
• How is the price used? (collateral valuation, settlement, display only)
• Testnet or mainnet target?

Outputs

• Move code that receives `&PriceInfoObject` and reads price with staleness check.
• TS client code using `@pythnetwork/pyth-sui-js` that fetches prices from Hermes and passes them in the same PTB.
• A verified testnet price read: one real transaction that reads a Pyth price on chain, observable on suiscan.
• Append to `.suiperpower/build-context.md`:

  ## pyth-oracle session, <timestamp>
  - feeds: <list of feed IDs>
  - staleness: <max_age_secs>
  - network: testnet | mainnet
  - hermes endpoint: <url>
  - pyth state id: <id>
  - wormhole state id: <id>
  - verified tx digest: <digest>
  - open issues: <list>

The skill never deletes files outside the integration source path without explicit user confirmation.

Architecture: the pull model

Pyth is a pull oracle. The price lives off chain on Hermes servers. Your client fetches a signed price update, then passes it on chain in the same PTB that reads the price. The flow:

1. TS client calls Hermes: getPriceFeedsUpdateData([feedId])
2. TS client builds PTB:
   a. pythClient.updatePriceFeeds(tx, updateData, [feedId])  -> PriceInfoObject IDs
   b. tx.moveCall your_module::use_price(priceInfoObjectId, clock, maxAge)
3. User signs and executes the PTB
4. Your Move contract reads price from &PriceInfoObject via get_price_no_older_than

Your Move contract never calls Pyth update functions directly. It only receives `&PriceInfoObject` as a parameter. The TS SDK handles updates. This is critical because the Pyth package ID changes on upgrades, and hard-coding it in Move would brick your contract.

Workflow

1. **Context gathering**

• Read `.suiperpower/build-context.md` if it exists.
• Confirm which asset prices are needed and the staleness tolerance.
• Decide testnet or mainnet. Default to testnet for development.

2. **Add Move dependency**

• Add Pyth to `Move.toml`. See `references/pyth-quickstart.md` for the exact config.
• Use `rev = "sui-contract-testnet"` for testnet, `"sui-contract-mainnet"` for mainnet.
• Also add the Wormhole dependency (Pyth requires it).

3. **Write the Move contract**

• Accept `&PriceInfoObject` and `&Clock` as function parameters.
• Call `pyth::pyth::get_price_no_older_than(price_info_object, clock, max_age)` for staleness-checked reads.
• Use `price::get_price()`, `price::get_expo()`, `price::get_conf()` to extract values.
• Handle the exponent correctly: the raw price is `value * 10^expo`. See `references/pyth-pitfalls.md`.
• Never hard-code any Pyth package ID or update call in Move.

4. **Write the TS client**

• Install `@pythnetwork/pyth-sui-js`.
• Create `SuiPriceServiceConnection` pointing to the right Hermes endpoint (no extra config needed).
• Create `SuiPythClient(suiClient, pythStateId, wormholeStateId)` for the target network.
• Build a PTB: `updatePriceFeeds` first, then your `moveCall` with the returned `PriceInfoObject` IDs.
• See `references/pyth-quickstart.md` for the full pattern.

5. **Look up feed IDs**

• Use the Hermes API: `GET https://hermes.pyth.network/v2/price_feeds?query=<symbol>&asset_type=crypto`
• Common feeds listed in `references/pyth-quickstart.md`.