# Canonical: https://www.uddalak.xyz/hyperliquid-academy/article/80-hyperliquid-l1-read-precompiles-complete-guide
# Author: Uddalak Das
# Last source: https://www.uddalak.xyz/hyperliquid-academy/article/80-hyperliquid-l1-read-precompiles-complete-guide

---
title: "Hyperliquid L1 Read Precompiles: Complete Guide"
description: "Hyperliquid L1 read precompiles let HyperEVM contracts query selected HyperCore state directly at protocol-defined addresses, avoiding a separate offchain oracle for supported data."
pillar: "Architecture & Build"
track: "Architecture & Build"
cluster: "Architecture & Build"
level: "Advanced"
primary_icp: ["builder", "smart contract developer"]
secondary_icp: []
content_type: "reference"
reading_time: "3 min"
last_reviewed: "2026-09-07"
last_verified: "2026-09-07"
volatile: true
prerequisites: ["31-hypercore-hyperevm-precompiles", "53-hypercore-vs-hyperevm"]
related: ["81-corewriter-actions-complete-reference", "54-hyperliquid-state-what-lives-where"]
---

# Hyperliquid L1 Read Precompiles: Complete Guide

L1 read precompiles are the native read bridge from HyperEVM into HyperCore. A contract calls protocol-defined addresses beginning in the `0x...0800` range and receives data such as perpetual positions, spot balances, vault equity, staking delegations, oracle prices, or the L1 block number. The returned values correspond to the latest HyperCore state available when the EVM block is constructed.

## Why a precompile instead of a normal contract

A normal Solidity contract can only read state exposed inside the EVM unless an oracle or message-passing system imports outside information. HyperCore state is not ordinary Solidity storage. Precompiles give the EVM a protocol-native function for selected reads.

This is valuable because an application can reference native financial state without trusting an application-operated indexing server as the final source.

## Addresses, inputs, and scaling

The official `L1Read.sol` interface documents each precompile and its ABI. Returned numerical values often use fixed-point representations whose scaling depends on the asset and its `szDecimals`. Developers must apply the documented conversion rather than assuming 18-decimal EVM conventions.

A wrong scale factor can be more dangerous than a reverted call because it produces plausible but incorrect prices or sizes.

## Failure and gas behavior

Invalid inputs can cause a precompile call frame to consume the gas provided to it. Current documentation specifies a gas-cost formula based on input and output length. Contracts should therefore validate asset identifiers and addresses before making reads where possible.

A protocol read is still part of EVM execution and should be included in gas estimates.

## State timing

The value corresponds to HyperCore state when the EVM block is built. It is not a promise that every offchain API response observed a millisecond later will have the same timestamp.

Applications that combine precompile state with external feeds should define which timestamp and source governs each decision.

## Design patterns

Precompiles are useful for collateral checks, position-aware vault logic, native-price references, staking-aware applications, and protocols that need to inspect HyperCore balances before taking action.

Keep business logic separate from decoding. A small audited library that wraps the protocol interface is safer than duplicating byte-level conversions throughout a codebase.

## How this connects

Start with [How HyperCore and HyperEVM Communicate](/hyperliquid-academy/article/31-hypercore-hyperevm-precompiles), [HyperCore vs HyperEVM: Which Layer Does What?](/hyperliquid-academy/article/53-hypercore-vs-hyperevm) if the underlying concept is unfamiliar. Related reading: [CoreWriter Actions: Complete Reference](/hyperliquid-academy/article/81-corewriter-actions-complete-reference), [Understanding Hyperliquid State: What Lives Where?](/hyperliquid-academy/article/54-hyperliquid-state-what-lives-where).

## Sources

- https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/hyperevm/interacting-with-hypercore