API reference

redstone

redstone-py: a typed sync + async Python client for the RedStone oracle API.

Example

from redstone import RedStoneClient with RedStoneClient() as client: ... client.get_latest_value("ETH") # doctest: +SKIP 1726.41

AsyncRedStoneClient

An asynchronous client for the RedStone oracle HTTP API.

This mirrors :class:~redstone.client.RedStoneClient but exposes async methods backed by :class:httpx.AsyncClient. Use it as an async context manager to ensure the connection pool is closed::

async with AsyncRedStoneClient() as client:
    price = await client.get_latest_value("ETH")

Parameters:

Name	Type	Description	Default
base_url	str	Base URL of the RedStone API. Defaults to https://api.redstone.finance.	DEFAULT_BASE_URL
provider	str	Default provider id used when a method does not specify one. Defaults to "redstone".	DEFAULT_PROVIDER
timeout	float	Per-request timeout in seconds.	DEFAULT_TIMEOUT
client	Optional[AsyncClient]	An optional pre-configured :class:httpx.AsyncClient. When supplied, the caller is responsible for closing it.	None

aclose() async

Close the underlying HTTP client if this instance owns it.

get_price(symbol, provider=None) async

Fetch the latest price point for a single symbol.

Parameters:

Name	Type	Description	Default
symbol	str	The data-feed symbol to query, e.g. "ETH".	required
provider	Optional[str]	Provider id to query. Defaults to the client's provider.	None

Returns:

Type	Description
PricePoint	The latest :class:~redstone.models.PricePoint for the symbol.

Raises:

Type	Description
RedStoneNotFoundError	If no price data is available for the symbol.
RedStoneAPIError	If the API returns an error response.

get_latest_value(symbol, provider=None) async

Fetch just the latest aggregated price value for a symbol.

Parameters:

Name	Type	Description	Default
symbol	str	The data-feed symbol to query, e.g. "ETH".	required
provider	Optional[str]	Provider id to query. Defaults to the client's provider.	None

Returns:

Type	Description
float	The latest price as a float.

Raises:

Type	Description
RedStoneNotFoundError	If no price data is available for the symbol.
RedStoneAPIError	If the API returns an error response.

get_prices(symbols, provider=None) async

Fetch the latest price points for several symbols at once.

Parameters:

Name	Type	Description	Default
symbols	Sequence[str]	The data-feed symbols to query, e.g. ["ETH", "BTC"].	required
provider	Optional[str]	Provider id to query. Defaults to the client's provider.	None

Returns:

Type	Description
dict[str, PricePoint]	A mapping of symbol to its latest :class:~redstone.models.PricePoint.

Raises:

Type	Description
RedStoneAPIError	If the API returns an error response.

get_historical_prices(symbol, from_timestamp, to_timestamp, interval=None, provider=None) async

Fetch historical price points for a symbol over a time range.

Parameters:

Name	Type	Description	Default
symbol	str	The data-feed symbol to query, e.g. "ETH".	required
from_timestamp	int	Range start as a Unix epoch in milliseconds.	required
to_timestamp	int	Range end as a Unix epoch in milliseconds.	required
interval	Optional[int]	Optional sampling interval in milliseconds (e.g. 3600000 for hourly).	None
provider	Optional[str]	Provider id to query. Defaults to the client's provider.	None

Returns:

Type	Description
list[PricePoint]	A list of :class:~redstone.models.PricePoint ordered by the API.

Raises:

Type	Description
RedStoneAPIError	If the API returns an error response.

RedStoneClient

A synchronous client for the RedStone oracle HTTP API.

The client wraps the public, keyless /prices endpoints of the RedStone cache layer, returning typed :class:~redstone.models.PricePoint objects.

It can be used as a context manager to ensure the underlying HTTP connection pool is closed::

with RedStoneClient() as client:
    price = client.get_latest_value("ETH")

Parameters:

Name	Type	Description	Default
base_url	str	Base URL of the RedStone API. Defaults to https://api.redstone.finance.	DEFAULT_BASE_URL
provider	str	Default provider id used when a method does not specify one. Defaults to "redstone".	DEFAULT_PROVIDER
timeout	float	Per-request timeout in seconds.	DEFAULT_TIMEOUT
client	Optional[Client]	An optional pre-configured :class:httpx.Client to use. When supplied, the caller is responsible for closing it.	None

close()

Close the underlying HTTP client if this instance owns it.

get_price(symbol, provider=None)

Fetch the latest price point for a single symbol.

Parameters:

Name	Type	Description	Default
symbol	str	The data-feed symbol to query, e.g. "ETH".	required
provider	Optional[str]	Provider id to query. Defaults to the client's provider.	None

Returns:

Type	Description
PricePoint	The latest :class:~redstone.models.PricePoint for the symbol.

Raises:

Type	Description
RedStoneNotFoundError	If no price data is available for the symbol.
RedStoneAPIError	If the API returns an error response.

get_latest_value(symbol, provider=None)

Fetch just the latest aggregated price value for a symbol.

Parameters:

Name	Type	Description	Default
symbol	str	The data-feed symbol to query, e.g. "ETH".	required
provider	Optional[str]	Provider id to query. Defaults to the client's provider.	None

Returns:

Type	Description
float	The latest price as a float.

Raises:

Type	Description
RedStoneNotFoundError	If no price data is available for the symbol.
RedStoneAPIError	If the API returns an error response.

get_prices(symbols, provider=None)

Fetch the latest price points for several symbols at once.

Parameters:

Name	Type	Description	Default
symbols	Sequence[str]	The data-feed symbols to query, e.g. ["ETH", "BTC"].	required
provider	Optional[str]	Provider id to query. Defaults to the client's provider.	None

Returns:

Type	Description
dict[str, PricePoint]	A mapping of symbol to its latest :class:~redstone.models.PricePoint.

Raises:

Type	Description
RedStoneAPIError	If the API returns an error response.

get_historical_prices(symbol, from_timestamp, to_timestamp, interval=None, provider=None)

Fetch historical price points for a symbol over a time range.

Parameters:

Name	Type	Description	Default
symbol	str	The data-feed symbol to query, e.g. "ETH".	required
from_timestamp	int	Range start as a Unix epoch in milliseconds.	required
to_timestamp	int	Range end as a Unix epoch in milliseconds.	required
interval	Optional[int]	Optional sampling interval in milliseconds (e.g. 3600000 for hourly).	None
provider	Optional[str]	Provider id to query. Defaults to the client's provider.	None

Returns:

Type	Description
list[PricePoint]	A list of :class:~redstone.models.PricePoint ordered by the API.

Raises:

Type	Description
RedStoneAPIError	If the API returns an error response.

RedStoneAPIError

Bases: RedStoneError

Raised when the RedStone API returns a non-success HTTP status.

Attributes:

Name	Type	Description
status_code		The HTTP status code returned by the API, if known.

RedStoneError

Bases: Exception

Base class for all errors raised by redstone-py.

RedStoneNotFoundError

Bases: RedStoneError

Raised when a requested symbol has no available price data.

PricePoint

Bases: BaseModel

A single price observation returned by the RedStone oracle API.

Each point represents the aggregated value of a data feed (symbol) as signed by a given provider at a specific timestamp. The optional source map breaks the aggregate down into the individual venue prices that fed into it.

Attributes:

Name	Type	Description
id	Optional[str]	Server-assigned identifier for the price record, when present.
symbol	str	The data-feed symbol, e.g. "ETH" or "BTC".
provider	Optional[str]	The provider identifier or public key that signed the value.
value	float	The aggregated price expressed in the feed's quote currency.
timestamp	int	Observation time as a Unix epoch in milliseconds.
source	Optional[dict[str, float]]	Optional per-venue prices keyed by "<exchange>-<quote>".
lite_evm_signature	Optional[str]	Optional lightweight EVM signature of the payload.
permaweb_tx	Optional[str]	Optional Arweave transaction id where the data is stored.
provider_public_key	Optional[str]	Optional public key of the signing provider.