Datasets

Dataset plugins — fetchDataset contract. The only built-in is defillama-tvl. GeckoTerminal pool candles are the geckoterminal-ohlcv source.

This page

Manuals

Section PDFPlugins Full PDFComplete

Abstract

A dataset plugin loads an alternate series through fetchDataset. The only built-in is defillama-tvl (BUILTIN_DATASETS in src/onchain/catalog.ts). GeckoTerminal pool candles are source geckoterminal-ohlcv, with the client in src/onchain/geckoterminal.ts and the Worker gecko proxy. They are not a dataset id. Derived TVL spike events come from src/onchain/events.ts. UI: On-Chain panel.

Conceptual model

Rendering…

Interface surface

interface DatasetPlugin {
  id: string;
  name: string;
  kind: 'dataset';
  fetchDataset(opts: DatasetFetchOpts): Promise<OnchainDataset>;
  searchInstruments?(query: string, config?: Record<string, unknown>): Promise<OnchainInstrument[]>;
  capabilities?: { needsNetwork?: boolean; needsProxy?: boolean; /* … */ };
}

`DatasetFetchOpts`

Field	Notes
`instrument`	`chainId`, optional `protocolId` / `address`, `metric`, optional `facet`, `symbol` label
`resolution`	e.g. `1d`, `1h`
`startTime` / `endTime`	unix seconds (optional window)
`limit`	optional max points
`signal`	`AbortSignal`
`config`	plugin config bag (`baseUrl`, …)

`OnchainDataset`

Field	Notes
`kind`	`ohlcv` \| `scalar_series` \| `multi_series` \| `events` \| `table`
`points` / `series` / `bars` / `events`	payload shape depends on kind
`provenance`	`{ provider, queryId?, url? }` — required for UI honesty
`finality`	`pending` \| `safe` \| `finalized` \| `unknown`
`synthetic`	true when OHLC was synthesized from marks

Providers

id	Name	Network	Notes
`defillama-tvl`	DatasetPlugin	yes	Protocol TVL history; browser uses the Worker llama proxy by default
`geckoterminal-ohlcv`	source, not a dataset	yes	DEX pool OHLCV. Client `src/onchain/geckoterminal.ts`; browser uses the Worker gecko proxy

Helpers (not only plugins):

Module	Role
`src/onchain/defillama.ts`	Protocol TVL fetch + history parse
`src/onchain/geckoterminal.ts`	Pool OHLCV parse/map, search, interval/network maps
`src/onchain/events.ts`	`buildTvlSpikeEvents` from scalar TVL points
`src/onchain/proxy.ts`	`resolveDefiLlamaBaseUrl` / `resolveGeckoTerminalBaseUrl`

Worker proxy (CORS)

Default bases (when plugin config.baseUrl is empty):

{store.endpoint}/api/onchain/llama
{store.endpoint}/api/onchain/gecko

DefiLlama

Client path	Worker	Upstream
`/protocols`	`GET /api/onchain/llama/protocols`	`https://api.llama.fi/protocols`
`/protocol/:slug`	`GET /api/onchain/llama/protocol/:slug`	`https://api.llama.fi/protocol/:slug`

GeckoTerminal

Client path	Worker	Upstream
`/networks/:net/pools/:addr/ohlcv/:tf`	`GET /api/onchain/gecko/networks/.../ohlcv/...`	`https://api.geckoterminal.com/api/v2/networks/.../ohlcv/...`
`/search/pools`	`GET /api/onchain/gecko/search/pools`	`https://api.geckoterminal.com/api/v2/search/pools`

Allowlisted query keys:

OHLCV: aggregate, limit, currency, before_timestamp
Search: query, network, page, include

Address validation on the Worker: EVM 0x[a-fA-F0-9]{40} or Solana-style base58 ^[1-9A-HJ-NP-Za-km-z]{32,48}$. Network ids: ^[a-z0-9_]+$.

Resolver: src/onchain/proxy.ts. Handler: worker/src/onchain.ts.

On-Chain data (end user)
Worker overview — /api/onchain/… route table
Sources — OHLCV (separate plane)
Contracts — shared plugin base