WDK logoWDK documentation
StartWalletsDeFi & FiatAI & CLITools

Configuration

Configure HTTP pricing clients and providers

Create a Client

Every pricing client implements the same PricingClient interface. Create the one for your data source; the examples on this page then work with either.

Create a Bitfinex client
import { BitfinexPricingClient } from '@tetherto/wdk-pricing-bitfinex-http'

const client = new BitfinexPricingClient()

Neither client needs options to start. See Bitfinex Client Options on this page and the CoinGecko configuration for API keys and symbol mappings.

Fetch Prices

Current Price

The client returns a price when its provider can quote the pair, and null when it cannot.

Get Current Price
const price = await client.getCurrentPrice('BTC', 'USD')

if (price === null) {
  // Show an unavailable-price state in your UI
}

Batch Current Prices

Batch lookups return results in the same order as the input list. Entries that cannot be resolved are null.

Get Batch Current Prices
const prices = await client.getMultiCurrentPrices([
  { from: 'BTC', to: 'USD' },
  { from: 'ETH', to: 'USD' }
])

Batch Price Data

Use getMultiPriceData() when you need the last price plus 24-hour absolute and relative change.

Get Batch Price Data
const priceData = await client.getMultiPriceData([
  { from: 'BTC', to: 'USD' }
])

Historical Series

Supply start and end as Unix timestamps in milliseconds; both fields are required by HistoricalPriceOptions. Keep start within the trailing 365 days: the Bitfinex client, and the CoinGecko client on its public or Demo host, reject older ranges. This example requests the last 24 hours:

Get Historical Prices
const end = Date.now()
const start = end - 24 * 60 * 60 * 1000
const series = await client.getHistoricalPrice('BTC', 'USD', {
  start,
  end
})

Provider Integration

Pass any PricingClient to @tetherto/wdk-pricing-provider to add in-memory caching of the last price.

You can pass a single client or an array of clients. With an array, failures matching error instanceof Error trigger failover within the configured retries limit, including application and HTTP errors. A resolved null does not trigger failover.

Single client
import { PricingProvider } from '@tetherto/wdk-pricing-provider'

const provider = new PricingProvider({
  client,
  priceCacheDurationMs: 60 * 60 * 1000 // optional, defaults to 1h
})

const last = await provider.getLastPrice('BTC', 'USD')
const prices = await provider.getMultiLastPrices([
  { from: 'BTC', to: 'USD' },
  { from: 'ETH', to: 'USD' }
])
const end = Date.now()
const start = end - 24 * 60 * 60 * 1000
const hist = await provider.getHistoricalPrice('BTC', 'USD', {
  start,
  end
})

To enable failover, pass an ordered array of PricingClient instances. The provider advances through that array when a failure matches error instanceof Error, up to the retries limit.

Failover across multiple clients
import { PricingProvider } from '@tetherto/wdk-pricing-provider'

const provider = new PricingProvider({
  client: [primaryClient, secondaryClient, tertiaryClient],
  retries: 3 // optional, defaults to 3
})

const last = await provider.getLastPrice('BTC', 'USD')

The order of the array sets the priority. This example tries Bitfinex first and fails over to CoinGecko; swap the two entries to make CoinGecko the primary source:

Combine Bitfinex and CoinGecko
import { PricingProvider } from '@tetherto/wdk-pricing-provider'
import { BitfinexPricingClient } from '@tetherto/wdk-pricing-bitfinex-http'
import { CoingeckoPricingClient } from '@tetherto/wdk-pricing-coingecko-http'

const provider = new PricingProvider({
  client: [
    new BitfinexPricingClient(),
    new CoingeckoPricingClient({ apiKey: process.env.COINGECKO_API_KEY })
  ],
  retries: 1
})

Bitfinex Client Options

In @tetherto/wdk-pricing-bitfinex-http beta.6, pass common ticker symbols to the client methods. Symbols are case-insensitive: USDT and usdt both use Bitfinex's UST currency code for USD₮. The same translation applies to current prices, batch price data, and historical lookups.

Currency-Code Overrides (optional)

Use the optional currencyCodes object to set explicit common-symbol-to-Bitfinex-code mappings. Entries take precedence over built-in mappings and remote aliases. Both keys and values are uppercased.

For example, these explicit BTC and USD mappings let the client resolve that pair without fetching the remote alias map:

Set Currency-Code Overrides
import { BitfinexPricingClient } from '@tetherto/wdk-pricing-bitfinex-http'

const mappedClient = new BitfinexPricingClient({
  currencyCodes: { btc: 'btc', usd: 'usd' }
})

const price = await mappedClient.getCurrentPrice('BTC', 'USD')

For symbols without an explicit or built-in mapping, the client looks up Bitfinex's aliases and caches a successful lookup for that client instance. An unknown or ambiguous alias falls back to the uppercased input symbol. If the alias lookup fails, the client uses that fallback and retries the alias lookup on a later request. Translation does not add support for pairs Bitfinex cannot quote, and errors from price requests can still reject the call.

Direct Quotes Only

Current-price lookups use Bitfinex's FX conversion endpoint, and getMultiPriceData() uses Bitfinex ticker data. Both return a result only when Bitfinex can quote the pair directly. Unsupported pairs return null; the client does not try a USD-pivot fallback.

Unsupported Pair
const unsupported = await mappedClient.getCurrentPrice('BTC', 'BRL') // null when Bitfinex has no direct quote

Historical Results

Long histories are downscaled to ≤ 100 points. The concrete Bitfinex result uses { price, ts }, with ts in Unix milliseconds. The inherited HistoricalPriceResult declaration instead names the time field timestamp; this is a declaration/runtime mismatch. See the historical API notes before consuming the series in TypeScript.

CoinGecko Client Options

The CoinGecko client takes an API key, a Pro host, and symbol-to-coin-ID mappings. It throws for a from symbol missing from its coinIds map. See the CoinGecko configuration and error handling pages.


Need Help?

On this page