Skip to content

API ReferencePricing and oraclesInterface

PricingModule

Price operations: Pyth token-pair and USD prices, the signed price updates that priced transactions carry, and the fees and freshness window for those updates.

Reach it as sdk.pricing on an AnvilSDK instance, which creates the module for you.

Methods

getMaxPriceUpdateSecondsAgo()

getMaxPriceUpdateSecondsAgo(): Promise<number>;

Returns how many seconds old an oracle price update may be and still be accepted by the LetterOfCredit contract.

The value includes a UX buffer, so it is deliberately shorter than the contract’s own window and will not match it exactly. It is the single place that buffer is applied — treat the result as the effective freshness window rather than subtracting a margin again.

Returns

Promise<number>

The effective freshness window, in seconds.


getOraclePriceUpdate()

getOraclePriceUpdate(params): Promise<OraclePriceUpdate>;

Returns the Pyth oracle price update that must accompany any LetterOfCredit call whose outcome depends on a price — creating or modifying a Dynamic LOC, most notably.

The result carries the fee Pyth charges to process the update onchain. That fee must be passed as the transaction’s value, so treat the update and its fee as a unit. Fetch it immediately before sending: an update goes stale within PricingModule.getMaxPriceUpdateSecondsAgo seconds.

Parameters

ParameterTypeDescription
paramsGetOraclePriceUpdateParamsThe token pair the update must cover.
params.inputToken`0x${string}`The token being priced (the base asset), such as a Dynamic LOC’s collateral token.
params.outputToken`0x${string}`The token it is priced in (the quote asset), such as a Dynamic LOC’s credited token.

Returns

Promise<OraclePriceUpdate>

The price update bytes and the fee required to submit them.

Throws

StalePythPriceError If Hermes returns a price outside oracleConfig.maxPriceAgeSeconds.


getOraclePriceUpdateFee()

getOraclePriceUpdateFee(params): Promise<bigint>;

Returns the fee Pyth charges to submit the given price update bytes onchain. PricingModule.getOraclePriceUpdate already reports this for the update it returns; call this only when you hold update bytes from elsewhere.

Parameters

ParameterTypeDescription
paramsGetOraclePriceUpdateFeeParamsThe price update bytes to be submitted.
params.priceUpdateBytes`0x${string}`ABI-encoded Pyth update data, exactly as returned in OraclePriceUpdate.data. The fee is what the transaction must send as value.

Returns

Promise<bigint>

The fee, in wei, to send as the transaction value.


getPrice()

getPrice(params): Promise<Price>;

Returns the current Pyth exchange rate from inputToken to outputToken as a Price in smallest units of output per smallest unit of input, computed with the same integer math the onchain PythPriceOracle uses. Both tokens need a Pyth feed.

Because both tokens’ decimals are already folded into the result, it can be handed to contract math as-is; rescale only to display a human-readable rate.

Parameters

ParameterTypeDescription
paramsGetPriceParamsThe token being priced and the token to price it in.
params.inputToken`0x${string}`The token that would be input into the price calculation inputToken * price = outputToken. In forex trading, this is commonly referred to as the base asset.
params.outputToken`0x${string}`The token output from the price calculation inputToken * price = outputToken. In forex trading, this is commonly referred to as the quote asset.

Returns

Promise<Price>

The output-per-unit-input price between the two tokens.

Example

const { price, exponent } = await sdk.pricing.getPrice({
inputToken: WETH,
outputToken: USDC,
});
// price * 10**exponent = USDC smallest units per 1 wei; both tokens'
// decimals are already folded in, so on-chain math uses it as-is. Rescale
// by (18 - 6) only to show USDC per whole WETH.
const usdcPerWholeWeth =
Number(price) * 10 ** (Number(exponent) + 18 - 6);

Throws

StalePythPriceError If Hermes returns a price outside oracleConfig.maxPriceAgeSeconds. The SDK does not fall back to the onchain price for a stale price; that fallback applies only when Hermes is unreachable.


getPriceFeedId()

getPriceFeedId(params): Promise<string>;

Returns the Pyth price feed ID for a token. The onchain PythPriceOracle is consulted first, falling back to the Pyth Hermes API when the oracle does not know the token.

Most integrations never need this directly — PricingModule.getPrice and PricingModule.getOraclePriceUpdate resolve feed IDs themselves. Reach for it when you are driving Pyth yourself.

Parameters

ParameterTypeDescription
paramsGetPriceFeedIdParamsThe token to look up.
params.tokenAddress`0x${string}`Token whose Pyth price-feed ID to resolve. The onchain PythPriceOracle mapping is tried first, then Pyth Hermes by symbol.

Returns

Promise<string>

The Pyth price feed ID.


getTokenPairPrice()

getTokenPairPrice(params): Promise<TokenPairPrice>;

Returns the same price as PricingModule.getPrice, together with the token pair and the source that answered: 'hermes', or 'chainOracle' when Hermes was unreachable and the SDK fell back to a fresh onchain price.

Parameters

ParameterTypeDescription
paramsGetPriceParamsThe token being priced and the token to price it in. Fields as listed under getPrice.

Returns

Promise<TokenPairPrice>

The price in smallest units, the token pair, and its source.

Throws

StalePythPriceError If Hermes returns a price outside oracleConfig.maxPriceAgeSeconds.

Throws

PriceServerError If Hermes is unreachable and no fresh onchain price is available.


getUsdPrice()

getUsdPrice(params): Promise<Price>;

Returns the USD price of a token, expressed as cents per most granular unit of the token. This is not how a price is usually displayed — scale by the token’s decimals before showing it to a person.

Parameters

ParameterTypeDescription
paramsGetUsdPriceParamsThe token being priced.
params.token`0x${string}`The token for which the USD price is being fetched. The returned Price is in cents per smallest unit of the token, not dollars per whole token.

Returns

Promise<Price>

The USD price of one smallest unit, in cents.

Throws

StalePythPriceError If Hermes returns a price outside oracleConfig.maxPriceAgeSeconds.


getUsdPrices()

getUsdPrices(params): Promise<UsdPriceOutcome[]>;

Returns best-effort USD display prices for a set of ERC-20 addresses and/or direct Pyth feed entries. After resolving address entries’ feed IDs (which may cost one Hermes symbol lookup per token absent from the onchain PythPriceOracle), the SDK batches the normalized set — address entries and feed entries together — into one Hermes latest-price request, while outcomes retain caller order and identify stale or unavailable entries individually. Only a failure of that one request rejects, so callers keep their last good prices. A feed entry (for a value with no ERC-20 address, such as native ETH) is priced directly by feed ID with no token resolution.

Parameters

ParameterTypeDescription
paramsGetUsdPricesParamsThe token addresses and/or feed entries to price.
params.tokensreadonly UsdPriceEntry[]Token addresses or direct Pyth feed entries to price. The returned outcomes preserve this order, including duplicates. Address entries are matched case-insensitively; feed entries are matched by normalized feed ID and decimals together, so the same feed named twice with different decimals still projects each entry’s own exponent. A mixed request issues one Hermes read for every distinct feed (by normalized feed ID alone) across both kinds of entry.

Returns

Promise<UsdPriceOutcome[]>

One discriminated outcome per supplied entry.

Throws

PriceServerError If the batched Hermes request itself fails.

Examples

const outcomes = await sdk.pricing.getUsdPrices({
tokens: [WETH, USDC],
});
for (const outcome of outcomes) {
// Narrow on `kind` before reading identity: an address entry's outcome
// carries `token: Address`, a feed entry's carries `key` instead (see
// the feed-entry example below).
if (outcome.kind !== 'address') continue;
if (outcome.status === 'fresh' || outcome.status === 'stale') {
console.log(outcome.token, outcome.status, outcome.price);
} else {
console.warn(outcome.token, outcome.reason);
}
}
const outcomes = await sdk.pricing.getUsdPrices({
tokens: [WETH, { feedId: ETH_USD_FEED_ID, decimals: 18, key: 'ETH' }],
});
for (const outcome of outcomes) {
// A mixed request returns a mix of kinds: narrow on `kind` before
// reading identity. Address entries carry `token: Address`; feed
// entries carry `key` (here, 'ETH') and have no `token` field.
const id = outcome.kind === 'address' ? outcome.token : outcome.key;
if (outcome.status === 'fresh' || outcome.status === 'stale') {
console.log(id, outcome.status, outcome.price);
} else {
console.warn(id, outcome.reason);
}
}