Dataline TypeScript SDK

A typed, framework-independent SDK for the Dataline Data API. It covers every operation in the pinned OpenAPI contract and supports API keys, bearer tokens, and accountless x402 challenges.

Status: initial open-source release. Confirm ownership of the @dataline npm scope before publishing.

Requirements

• Node.js 18 or newer
• TypeScript 5 or newer for TypeScript consumers

The package includes ESM, CommonJS, and TypeScript declarations. It has no production dependencies.

Installation

npm install @dataline/sdk

pnpm add @dataline/sdk

yarn add @dataline/sdk

Quick Start

import { Dataline } from '@dataline/sdk';

const client = new Dataline({
  apiKey: process.env.DATALINE_KEY,
});

const data = await client.price('BTC');
console.log(data.price);
console.log(data.confidence?.score);

price() is a convenience method for the CEX price endpoint. It adds numeric price and camelCase referencePrice fields while preserving the other contract data. Financial decimal fields in the contract remain strings to avoid accidental precision loss.

Authentication

Use a Dataline API key:

const client = new Dataline({ apiKey: process.env.DATALINE_KEY });

Use a JWT or OAuth access token:

const client = new Dataline({ accessToken: process.env.DATALINE_ACCESS_TOKEN });

When both are supplied, the bearer access token takes precedence and the API key is not sent.

Request accountless x402 access:

import { Dataline, DatalinePaymentRequiredError } from '@dataline/sdk';

const client = new Dataline({ accessMode: 'x402' });

try {
  await client.price('BTC');
} catch (error) {
  if (error instanceof DatalinePaymentRequiredError) {
    console.log(error.paymentRequired);
  }
}

The SDK exposes the typed HTTP 402 challenge. It does not spend funds or choose a wallet implementation automatically.

Keep credentials in server-side environment variables. Never embed secret API keys or bearer tokens in browser bundles, public source code, logs, or error reports.

Resource Examples

await client.health();
await client.me();

await client.cex.announcements.list({ query: 'listing', limit: 20 });
await client.cex.announcements.detail({ announcementId: '123' });

await client.crypto.projects.search({ query: 'bitcoin' });
await client.crypto.projects.detail({ projectId: 'bitcoin' });
await client.crypto.cexPrice({ base: 'BTC', quote: 'USD' });
await client.crypto.dexPrice({ chain: 'ethereum', contractAddress: '0x...' });
await client.crypto.history({ base: 'BTC', venue: 'binance', interval: '1h' });
await client.crypto.perpetuals.metrics({ base: 'BTC' });
await client.crypto.perpetuals.fundingHistory({ base: 'BTC', venue: 'binance' });
await client.crypto.perpetuals.openInterestHistory({ base: 'BTC', venue: 'binance' });

await client.defi.pools.list({ network: 'base' });
await client.defi.pools.search({ query: 'USDC' });
await client.defi.lending.variableRate.markets({ protocol: 'aave_v3' });
await client.defi.lending.variableRate.detail({ marketId: 'market-id' });
await client.defi.lending.variableRate.history({ marketId: 'market-id', interval: 'day' });
await client.defi.lending.vaults.list({ version: 'V2' });
await client.defi.lending.vaults.detail({ vaultAddress: '0x...' });
await client.defi.lending.vaults.history({ vaultAddress: '0x...', metric: 'apy' });
await client.defi.lending.fixedRate.markets({ protocol: 'morpho_midnight' });
await client.defi.lending.fixedRate.detail({ marketId: 'market-id' });
await client.defi.lending.fixedRate.orderbook({ marketId: 'market-id', side: 'all' });
await client.defi.lending.account.positions({ walletAddress: '0x...', protocol: 'All' });

await client.prediction.events.list({ query: 'election', limit: 20 });
await client.prediction.events.detail({ slug: 'event-slug' });

See API.md for the complete endpoint mapping. Public request and response types are inferred from the OpenAPI contract and exported from the package.

Requests, Cancellation, and Errors

All resource methods accept request options as their final argument:

import { DatalineError } from '@dataline/sdk';

const controller = new AbortController();

try {
  const result = await client.crypto.cexPrice(
    { base: 'ETH', quote: 'USD' },
    {
      signal: controller.signal,
      timeout: 10_000,
      maxRetries: 1,
      headers: { 'x-correlation-id': 'example-request' },
    },
  );
  console.log(result?.reference_price);
} catch (error) {
  if (error instanceof DatalineError) {
    console.error(error.status, error.code, error.requestId);
  }
}

Typed error subclasses cover authentication, validation, rate limiting, and payment-required responses. The SDK retries safe GET requests for transient network failures, HTTP 429, and selected 5xx statuses. It honors Retry-After and uses capped exponential backoff with jitter.

A custom fetch implementation can be provided through the constructor for compatible runtimes or testing:

const client = new Dataline({ apiKey: '...', fetch: customFetch });

Development

pnpm install
pnpm generate
pnpm validate

The source contract is pinned at openapi/openapi.json. Refresh and regenerate it with:

pnpm openapi:sync
pnpm check:openapi

Review contract changes before committing generated code. pnpm check:openapi fails if any operation lacks a public mapping. pnpm check:english enforces English-only maintained text.

Generate local API documentation with pnpm docs:build. Prepare user-visible changes with pnpm changeset. Publishing and remote Git operations are intentionally not automated without maintainer authorization.

License

MIT