> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# fundingHistory | Hyperliquid info
> The info endpoint with type: "fundingHistory" retrieves historical funding rates and premiums for a specific perpetual contract on the Hyperliquid exchange.
You can only use this endpoint on the official Hyperliquid public API. It is not available through Chainstack, as the open-source node implementation does not support it yet. See [Hyperliquid methods](/docs/hyperliquid-methods) for the full availability breakdown.
The `info` endpoint with `type: "fundingHistory"` retrieves historical funding rates and premiums for a specific perpetual contract on the Hyperliquid exchange. This endpoint provides comprehensive data about funding costs over time, enabling analysis of market sentiment, carry trade opportunities, and long-term trading strategy optimization.
## Parameters
### Request body
* `type` (string, required) — The request type. Must be `"fundingHistory"` to retrieve funding rate history.
* `coin` (string, required) — Asset symbol to retrieve funding history for (e.g., "BTC", "ETH", "SOL").
* `startTime` (integer, required) — Start timestamp in milliseconds, inclusive. Filters funding history from this time forward.
* `endTime` (integer, optional) — End timestamp in milliseconds, inclusive. Defaults to current time if not provided.
## Response
The response is an array of funding rate records, chronologically ordered from oldest to newest. Each record represents a funding rate snapshot taken at regular intervals (typically every 8 hours for most exchanges).
### Response structure
Each funding rate record contains:
**Asset identification:**
* `coin` — Asset symbol (e.g., "BTC", "ETH", "SOL")
**Funding metrics:**
* `fundingRate` — The funding rate applied to positions (decimal format)
* `premium` — Market premium component used in funding calculation
* `time` — Unix timestamp in milliseconds when the rate was applied
### Data interpretation
**Funding rate analysis:**
* Positive rates indicate longs pay shorts (bullish market bias)
* Negative rates indicate shorts pay longs (bearish market bias)
* Rate magnitude shows intensity of directional demand
**Premium components:**
* Premium represents the difference between perpetual and spot prices
* Combined with interest rate component to determine final funding rate
* Higher premiums suggest stronger directional pressure
**Time series patterns:**
* Funding rates typically reset every 8 hours
* Persistent positive funding indicates sustained bullish sentiment
* Rate volatility reflects changing market conditions
## Market analysis insights
### Sentiment indicators
**Directional bias measurement:**
* Consistently positive funding rates suggest bullish market structure
* Negative funding periods indicate bearish sentiment dominance
* Rate reversals often coincide with market trend changes
**Market efficiency:**
* Extreme funding rates indicate pricing inefficiencies
* Rate mean reversion suggests arbitrage opportunities
* Funding rate divergence across assets reveals relative strength
### Trading strategy applications
**Carry trade opportunities:**
* Identify assets with consistently favorable funding rates
* Calculate cumulative funding costs for position holding periods
* Optimize position timing around funding rate cycles
**Position management:**
* Avoid high-cost funding periods for direction-neutral strategies
* Time entries and exits around funding rate extremes
* Use funding rate trends for position sizing decisions
### Risk management
**Cost analysis:**
* Calculate total funding costs as percentage of trading profits
* Monitor funding rate volatility for strategy stability
* Assess impact of funding on long-term position holding
**Market timing:**
* Use funding rate extremes as contrarian indicators
* Identify potential trend reversal points
* Combine with other metrics for comprehensive market analysis
## Historical patterns
### Cycle analysis
**Funding rate cycles:**
* Identify recurring patterns in funding rate behavior
* Analyze seasonal effects and market cycle correlations
* Track funding rate recovery periods after extreme events
**Cross-asset comparison:**
* Compare funding rates across different perpetual contracts
* Identify relative value opportunities between assets
* Analyze correlation patterns during market stress
### Market structure insights
**Liquidity conditions:**
* High funding rate volatility often indicates lower liquidity
* Stable funding rates suggest efficient arbitrage mechanisms
* Rate spikes may indicate temporary liquidity shortages
**Institutional vs retail participation:**
* Funding rate patterns can reveal trader composition changes
* Professional arbitrageurs tend to stabilize funding rates
* Retail-driven markets often show more volatile funding patterns
## Example request
```shell Shell theme={"system"}
curl -X POST \
-H "Content-Type: application/json" \
-d '{
"type": "fundingHistory",
"coin": "BTC",
"startTime": 1681923833000
}' \
https://api.hyperliquid.xyz/info
```
```python Python (hyperliquid-python-sdk) theme={"system"}
from hyperliquid.info import Info
from hyperliquid.utils import constants
info = Info(constants.MAINNET_API_URL, skip_ws=True)
# Retrieve funding history for BTC from a given start time.
funding = info.funding_history(name="BTC", startTime=1681923833000)
print(funding)
```
```typescript TypeScript (@nktkas/hyperliquid) theme={"system"}
import * as hl from "@nktkas/hyperliquid";
const transport = new hl.HttpTransport();
const client = new hl.InfoClient({ transport });
// Retrieve funding history for BTC from a given start time.
const funding = await client.fundingHistory({
coin: "BTC",
startTime: 1681923833000,
});
console.log(funding);
```
## Use cases
The `info` endpoint with `type: "fundingHistory"` is essential for applications that need to:
* **Analyze funding trends**: Study historical funding rates to understand market sentiment patterns
* **Calculate funding costs**: Determine total funding expenses for long-term position holding
* **Strategy optimization**: Build funding-aware trading strategies and optimize position timing
* **Market analysis**: Analyze funding rate patterns for market sentiment and trend analysis
* **Risk management**: Assess funding cost impact on strategy performance and profitability
* **Arbitrage opportunities**: Identify periods with favorable funding rates for carry trades
* **Backtesting systems**: Include realistic funding costs in strategy simulation and testing
* **Performance attribution**: Separate trading gains from funding costs for accurate analysis
* **Research and analytics**: Study perpetual futures funding mechanisms and market dynamics
* **Automated alerts**: Set up notifications for funding rate threshold breaches or patterns
This endpoint provides comprehensive funding rate history, enabling sophisticated analysis of perpetual futures markets and the development of funding-aware trading strategies on the Hyperliquid platform.
## OpenAPI
````yaml openapi/hyperliquid_node_api/hypercore_info/info_funding_history.json post /info
openapi: 3.0.0
info:
title: Hyperliquid Node API
version: 1.0.0
description: This is an API for interacting with Chainstack Hyperliquid node.
servers:
- url: https://api.hyperliquid.xyz
security: []
paths:
/info:
post:
tags:
- hyperliquid operations
summary: info (fundingHistory)
description: >-
Retrieve historical funding rates and premiums for a specific perpetual
contract, providing insight into market sentiment and carry costs over
time.
operationId: infoFundingHistory
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- type
- coin
- startTime
properties:
type:
type: string
enum:
- fundingHistory
default: fundingHistory
description: >-
The request type. Must be 'fundingHistory' to retrieve
funding rate history.
coin:
type: string
default: BTC
description: >-
Asset symbol to retrieve funding history for (e.g., 'BTC',
'ETH', 'SOL')
startTime:
type: integer
default: 1681923833000
description: Start timestamp in milliseconds, inclusive.
endTime:
type: integer
description: >-
End timestamp in milliseconds, inclusive. Defaults to
current time if not provided.
example:
type: fundingHistory
coin: BTC
startTime: 1681923833000
responses:
'200':
description: Historical funding rates and premiums data
content:
application/json:
schema:
type: array
description: Array of funding rate records for the specified asset
items:
type: object
properties:
coin:
type: string
fundingRate:
type: string
premium:
type: string
time:
type: integer
format: int64
required:
- coin
- fundingRate
- premium
- time
example:
- coin: BTC
fundingRate: '-0.0006133368'
premium: '-0.0009133368'
time: 1683849600048
- coin: BTC
fundingRate: '-0.000745027'
premium: '-0.001045027'
time: 1683878400388
- coin: BTC
fundingRate: '0.0000125'
premium: '0.0001068963'
time: 1686204000106
````