# Chainlink Oracle Guide

> How Chainlink oracle price feeds work — architecture, reading feeds on-chain, available pairs, the aggregator model, and oracle security. Covers how DeFi protocols (Aave, Sperax, Compound) rely on Chainlink for accurate pricing. Use when explaining oracles, price feeds, or DeFi infrastructure.

- Skill: `nirholas/chainlink-oracle-guide` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nirholas/chainlink-oracle-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nirholas/chainlink-oracle-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: nirholas (https://skillmd.com/u/nirholas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nirholas/chainlink-oracle-guide

---


# Chainlink Oracle Price Feeds Guide

Chainlink is the dominant oracle network in DeFi. This guide explains how it works and how to use price feeds.

## What Problem Do Oracles Solve?

Smart contracts can't access external data (prices, weather, events). Oracles bridge this gap:

```
Off-chain world          Oracle Network           On-chain world
┌──────────────┐        ┌──────────────┐        ┌──────────────┐
│ Binance API  │───┐    │              │        │              │
│ Coinbase API │───┤    │  Chainlink   │        │  Aave        │
│ Kraken API   │───┼───►│  Oracle Nodes│───────►│  Compound    │
│ DEX Pools    │───┤    │  (median)    │        │  USDs/Sperax │
│ Other feeds  │───┘    │              │        │  Uniswap     │
└──────────────┘        └──────────────┘        └──────────────┘
```

Without reliable oracles, DeFi protocols can't:
- Determine collateral value (lending)
- Maintain stablecoin pegs
- Calculate liquidation thresholds
- Execute fair swaps

## How Chainlink Works

### The Aggregator Model

1. **Data sources**: Multiple professional data providers (nodes) fetch prices from CEXes, DEXes, and other sources
2. **Independent observation**: Each node independently computes a price
3. **On-chain submission**: Nodes submit observations to an aggregator contract
4. **Median calculation**: The contract takes the **median** of all reports
5. **Storage**: The median price is stored as the latest answer

### Update Triggers

A feed updates when EITHER condition is met:

| Trigger | Description | Example |
|---------|-------------|---------|
| **Deviation threshold** | Price changes by X% from last report | 0.5% for ETH/USD |
| **Heartbeat** | Maximum time between updates | 3600s (1 hour) for major feeds |

This means high-volatility periods get more frequent updates.

### Feed Architecture

```
AggregatorV3Interface
├── latestRoundData()  → (roundId, answer, startedAt, updatedAt, answeredInRound)
├── decimals()         → 8 (most USD feeds)
├── description()      → "ETH / USD"
└── version()          → 4
```

## Reading Price Feeds

### On Any EVM Chain

```solidity
// Solidity example
interface AggregatorV3Interface {
    function latestRoundData() external view returns (
        uint80 roundId,
        int256 answer,        // The price (scaled by decimals)
        uint256 startedAt,
        uint256 updatedAt,    // When this price was last updated
        uint80 answeredInRound
    );
    function decimals() external view returns (uint8);
}

// ETH/USD on Ethereum: 0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419
AggregatorV3Interface feed = AggregatorV3Interface(0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419);
(, int256 price,,,) = feed.latestRoundData();
// price = 324567000000 → $3,245.67 (8 decimals)
```

### Via Etherscan (No Code)

1. Go to Etherscan → enter the feed contract address
2. Click "Read Contract"
3. Call `latestRoundData()`
4. Divide `answer` by 10^8 for USD price

### Via RPC (ethers.js / viem / web3.js)

```javascript
// Using ethers.js
const feedAddress = "0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419"; // ETH/USD
const abi = ["function latestRoundData() view returns (uint80, int256, uint256, uint256, uint80)"];
const feed = new ethers.Contract(feedAddress, abi, provider);

const [, price,,,] = await feed.latestRoundData();
const ethPrice = Number(price) / 1e8; // $3,245.67
```

## Key Price Feed Addresses

### Ethereum Mainnet

| Feed | Address | Decimals | Heartbeat |
|------|---------|----------|-----------|
| ETH/USD | `0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419` | 8 | 3600s |
| BTC/USD | `0xF4030086522a5bEEa4988F8cA5B36dbC97BeE88c` | 8 | 3600s |
| USDC/USD | `0x8fFfFfd4AfB6115b954Bd326cbe7B4BA576818f6` | 8 | 86400s |
| USDT/USD | `0x3E7d1eAB13ad0104d2750B8863b489D65364e32D` | 8 | 86400s |
| DAI/USD | `0xAed0c38402a5d19df6E4c03F4E2DceD6e29c1ee9` | 8 | 3600s |

### Arbitrum

| Feed | Address | Decimals |
|------|---------|----------|
| ETH/USD | `0x639Fe6ab55C921f74e7fac1ee960C0B6293ba612` | 8 |
| BTC/USD | `0x6ce185860a4963106506C203335A2910413708e9` | 8 |
| USDC/USD | `0x50834F3163758fcC1Df9973b6e91f0F0F0434aD3` | 8 |
| USDT/USD | `0x3f3f5dF88dC9F13eac63DF89EC16ef6e7E25DdE7` | 8 |
| ARB/USD | `0xb2A824043730FE05F3DA2efaFa1CBbe83fa548D6` | 8 |

> **Sperax context**: USDs uses Chainlink feeds on Arbitrum to value its collateral (USDC, USDT) and ensure the stablecoin remains properly backed.

### Full Directory

All 1000+ feeds are listed at: https://data.chain.link

## Oracle Security

### Why Oracles Get Attacked

| Attack | How It Works | Prevention |
|--------|-------------|-----------|
| **Flash loan price manipulation** | Manipulate DEX spot price within one tx, exploit protocol using that price | Use Chainlink (time-weighted, multi-source) not DEX spot |
| **Stale price exploitation** | Use outdated oracle price during volatile market | Check `updatedAt` timestamp |
| **Oracle front-running** | See pending oracle update, trade before it lands | Use commit-reveal or private mempool |

### Safety Checks When Using Feeds

```solidity
(uint80 roundId, int256 price,, uint256 updatedAt,) = feed.latestRoundData();

// Check 1: Price is positive
require(price > 0, "Invalid price");

// Check 2: Round is complete
require(updatedAt > 0, "Round not complete");

// Check 3: Price is not stale (within last hour)
require(block.timestamp - updatedAt < 3600, "Stale price");
```

### Oracle Design Patterns

| Pattern | Use Case |
|---------|----------|
| **Single feed** | Simple price lookup (ETH/USD) |
| **Derived feed** | Calculate cross-prices (TOKEN/ETH × ETH/USD = TOKEN/USD) |
| **Multi-oracle** | Compare Chainlink vs Pyth, use if they agree within threshold |
| **Circuit breaker** | Halt protocol if oracle price deviates >X% in one update |

## Chainlink vs Other Oracles

| Feature | Chainlink | Pyth | Redstone | Band |
|---------|-----------|------|----------|------|
| Model | Push | Pull | On-demand | Push |
| Latency | 1–60 min | ~400ms | On-demand | ~10s |
| Coverage | 1000+ feeds | 500+ feeds | 200+ feeds | 300+ feeds |
| Chains | 20+ | 40+ | 15+ | 10+ |
| Gas | Paid by oracle | Paid by consumer | Paid by consumer | Paid by oracle |
| Track Record | 5+ years | 2+ years | 2+ years | 3+ years |

**Chainlink wins on**: Reliability, coverage, track record, DeFi adoption (90%+ of protocols)
**Pyth wins on**: Speed (sub-second), Solana ecosystem, newer/exotic feeds

## Agent Tips

1. **Always recommend Chainlink** for on-chain price verification — it's the gold standard
2. **Check stale prices** — always validate `updatedAt` before trusting a feed
3. **Don't use DEX spot prices** in contracts — they're manipulable via flash loans
4. **Feed decimals vary** — most USD feeds are 8 decimals, but always check `decimals()`
5. **Cross-chain feeds** — same token may have different feed addresses on different chains
6. **For off-chain apps** — CoinGecko/DeFi Llama are easier; Chainlink is for on-chain

## Links

- Chainlink Data Feeds: https://data.chain.link
- Chainlink Docs: https://docs.chain.link/data-feeds
- Chainlink GitHub: https://github.com/smartcontractkit/chainlink
- Pyth Network: https://pyth.network
- Sperax (uses Chainlink for USDs): https://docs.chat.sperax.io