read_contract_at scalar function

Example

Needs RPC · RPC required

-- Chainlink ETH/USD at one block per day

WITH as_of(day) AS (

SELECT day

FROM generate_series('2024-01-01'::DATE, '2024-01-07'::DATE, INTERVAL 1 DAY) AS t(day)

)

SELECT

day,

format_units(

(read_contract_at(

$client,

'0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419'::ADDRESS,

'[{"type":"function","name":"latestRoundData","inputs":[],"outputs":[{"name":"roundId","type":"uint80"},{"name":"answer","type":"int256"},{"name":"startedAt","type":"uint256"},{"name":"updatedAt","type":"uint256"},{"name":"answeredInRound","type":"uint80"}]}]'::JSON,

'latestRoundData',

block_at($client, day::TIMESTAMPTZ)

)).answer,

)::DOUBLE AS eth_usd

FROM as_of;

Enable JavaScript to run this sample in the notebook. The SQL preview above is still available for reference.

API reference

Exact signatures with descriptions, requirements, inputs, returns, and examples.

read_contract_at(CLIENT, ADDRESS, JSON, VARCHAR, BIGINT, ...args) # RPC required

Accepts a typed BIGINT block number, including a per-row block_at result. ABI and function_name must be literal or foldable. Pinned and execution CLIENT values reject the explicit selector.

Inputs

Name	Type	Use
`client`	CLIENT Readable EVM state represented by a live, pinned, or execution CLIENT.	requiredpositional
`to`	ADDRESS Contract address to call.	requiredpositional
`abi`	JSON Literal or foldable JSON ABI used for argument encoding and return typing.	requiredpositional
`function_name`	VARCHAR Constant ABI function name.	requiredpositional
`block_number`	BIGINT Non-negative BIGINT block number. NULL produces NULL without issuing an RPC call.	requiredpositional

Showing fewer

Returns

Name	Type
`result` dynamic	ABI-derived scalar or STRUCT A function with one output returns that value directly. A function with multiple outputs returns a STRUCT with fields named from ABI outputs, or output0, output1, and so on for unnamed outputs.

Guidance

Historical contract reads

Use read_contract_at when the block number is already a typed BIGINT value or comes from block_at.

The ABI and function name remain planning-time constants so the exact scalar or STRUCT return type can be inferred.

NULL block numbers return NULL without an RPC request.
Negative block numbers are rejected locally.
Use read_contract options instead when you need a block tag, on_error, or a dynamic return schema.

Related functions

Category and tags

Category: Chain reads
Tag: RPC