Token Prices

Use Prices() for DefiLlama's coins endpoints. The Free API covers current prices, historical prices, charts, percentage changes, first-seen prices, and a nearest-block lookup. GetHistoricalLiquidity is a Pro-only method.1

Coin identifiers

Pass token identifiers as chain:address; for CoinGecko assets use coingecko:id. A slice is accepted where an endpoint accepts multiple coins. The SDK escapes each identifier and joins the escaped values with commas in the URL path.

coins := []string{
    "coingecko:bitcoin",
    "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
}

An empty slice is rejected locally. Use a Unix timestamp in seconds for historical-price and block methods.2

Free operations

Method	Return type	Purpose
GetCurrentPrices(ctx, coins)	map[string]CoinPrice	Returns the latest records for token identifiers.
GetHistoricalPrices(ctx, coins, timestamp)	map[string]CoinPrice	Returns records at a Unix timestamp.
GetBatchHistoricalPrices(ctx, coins)	map[string]any	Returns multiple tokens at multiple timestamps.
GetChart(ctx, coins, opts)	map[string]any	Returns regularly spaced price data.
GetPercentageChange(ctx, coins, opts)	map[string]any	Returns price-change data.
GetFirstPrices(ctx, coins)	map[string]CoinPrice	Returns each coin's earliest available price record.
GetBlockAtTimestamp(ctx, chain, timestamp)	*Block	Returns the closest block to a timestamp.

Read current and historical prices

CoinPrice exposes Price, Symbol, Timestamp, Decimals, Confidence, and the complete source record in Raw.

prices, err := client.Prices().GetCurrentPrices(ctx, []string{
    "coingecko:bitcoin",
    "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
})
if err != nil {
    return err
}

btc, ok := prices["coingecko:bitcoin"]
if !ok {
    return fmt.Errorf("DefiLlama did not return bitcoin")
}
fmt.Printf("BTC: $%.2f at %d\n", btc.Price, btc.Timestamp)

at := time.Date(2025, time.January, 1, 0, 0, 0, 0, time.UTC).Unix()
historical, err := client.Prices().GetHistoricalPrices(ctx,
    []string{"coingecko:ethereum"}, at)
if err != nil {
    return err
}
fmt.Printf("ETH on 2025-01-01: $%.2f\n", historical["coingecko:ethereum"].Price)

Check map membership instead of interpreting a zero-value CoinPrice as a response. Prices are decoded as float64; use a decimal package in the calling application where exact arithmetic is required.2

Request price charts and changes

ChartOptions has optional pointer fields. A nil field is omitted from the query string. Span controls the number of data points, while Start, End, and Period are passed to DefiLlama unchanged.

chart, err := client.Prices().GetChart(ctx,
    []string{"coingecko:bitcoin"},
    &defillama.ChartOptions{
        Span:   defillama.Ptr(30.0),
        Period: defillama.Ptr("1d"),
    },
)
if err != nil {
    return err
}
fmt.Println("response keys:", len(chart))

changes, err := client.Prices().GetPercentageChange(ctx,
    []string{"coingecko:bitcoin"},
    &defillama.PercentageOptions{
        Timestamp:   defillama.Ptr(float64(time.Now().UTC().Unix())),
        LookForward: defillama.Ptr(false),
        Period:      defillama.Ptr("24h"),
    },
)

Chart and percentage responses are intentionally returned as map[string]any because their upstream shape may evolve. Consult the official coins reference before binding application logic to individual raw fields.1

Request batch history

GetBatchHistoricalPrices accepts a map from token identifier to timestamps. The SDK JSON-encodes that map for the required coins query parameter.

history, err := client.Prices().GetBatchHistoricalPrices(ctx, map[string][]int64{
    "coingecko:bitcoin":  {1735689600, 1735776000},
    "coingecko:ethereum": {1735689600, 1735776000},
})
if err != nil {
    return err
}
_ = history

Find a nearest block

block, err := client.Prices().GetBlockAtTimestamp(ctx, "ethereum", time.Now().UTC().Unix())
if err != nil {
    return err
}
fmt.Printf("block %d at %d\n", block.Height, block.Timestamp)

Pro token liquidity

With a Pro-configured client, call GetHistoricalLiquidity(ctx, token) to retrieve the token-liquidity response as map[string]any.

liquidity, err := client.Prices().GetHistoricalLiquidity(ctx,
    "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48")
if err != nil {
    return err
}
_ = liquidity

References