LiveInk Widget Documentation

Embed real-time financial data into any website with a single script tag. No backend required.

Getting Started

The LiveInk Widget is a lightweight, self-contained JavaScript snippet that automatically updates financial data displayed on your website. It works with any HTML page — no framework, no build step, no dependencies.

How it works:

1. You include the widget script on your page with your API key.
2. You mark HTML elements with data-liveink attributes specifying the data type.
3. The widget automatically fetches real-time data and updates those elements at the interval you configure.
4. Tooltips show the original value, source, and last update time.

Quick Start

Add the widget to your page in two steps:

Step 1 — Include the script

<script src="https://api.liveink.app/widget.js"
        data-key="LIK-xxxx-xxxx-xxxx"
        data-refresh="300"></script>

Step 2 — Add data attributes to your elements

<!-- Bitcoin price in USD -->
<span data-liveink="bitcoin_usd"
      data-liveink-prefix="$"
      data-liveink-decimals="0">Loading...</span>

<!-- EUR/USD exchange rate -->
<span data-liveink="eur_usd"
      data-liveink-decimals="4">Loading...</span>

<!-- Oil price with suffix -->
<span data-liveink="oil_wti"
      data-liveink-prefix="$"
      data-liveink-suffix=" /barrel"
      data-liveink-decimals="2">Loading...</span>

That’s it. The widget will automatically validate your key, fetch fresh data, and keep values updated.

Authentication

Every request to the LiveInk API requires a valid API key, passed via the data-key attribute on the script tag. The widget handles authentication automatically.

Key format

API keys follow the pattern LIK-xxxx-xxxx-xxxx where each segment is an alphanumeric string.

Domain restriction

Each key is bound to one or more allowed domains. Requests from unauthorized domains will be rejected with a DOMAIN_NOT_ALLOWED error. Wildcards (*) are supported for development.

Validation flow

1. Widget loads
2. POST /api/widget/validate  Headers: X-LiveInk-Key: LIK-xxxx-xxxx-xxxx
3. Server checks:
   - Key exists and is active
   - Key has not expired
   - Request origin matches allowed domains
   - Daily request limit not exceeded
4. If valid -> fetch data  |  If invalid -> console warning

HTML Attributes

Use these attributes on any HTML element to control widget behavior:

Script tag attributes

Element attributes

Available Data Types

Each data-liveink value maps to a specific data feed. Data is fetched in batches and cached with category-specific TTLs (see the Refresh column below).

Cryptocurrency

Real-time prices from CoinGecko API (free tier, no key required).

Forex

Exchange rates from ECB via ExchangeRate-API (free, updated daily).

Energy / Commodities

Commodity prices from Yahoo Finance (real-time market data).

Precious Metals

Spot prices from Metals API and market aggregators.

Agriculture

Agricultural commodity prices from Commodities API.

Stock Indices

Major global stock indices from Yahoo Finance.

Interest Rates

Central bank reference rates, updated after each policy meeting.

Macro Economics

Key macroeconomic indicators, sourced from national statistics offices and international organizations.

Weather

Current temperature data from OpenWeatherMap and Open-Meteo.

Air Quality

Air Quality Index from WAQI / aqicn.org.

Earthquake

Latest significant seismic events from USGS Earthquake API.

Demographics

Population data from World Bank and national statistics offices.

Code Examples

Basic article with live data

<article>
  <h1>Market Update</h1>
  <p>
    Bitcoin is currently trading at
    <span data-liveink="bitcoin_usd"
          data-liveink-prefix="$"
          data-liveink-decimals="0">...</span>,
    while Ethereum sits at
    <span data-liveink="ethereum_usd"
          data-liveink-prefix="$"
          data-liveink-decimals="2">...</span>.
  </p>
  <p>
    The EUR/USD exchange rate is at
    <span data-liveink="eur_usd"
          data-liveink-decimals="4">...</span>,
    and WTI Oil is at
    <span data-liveink="oil_wti"
          data-liveink-prefix="$"
          data-liveink-suffix=" per barrel"
          data-liveink-decimals="2">...</span>.
  </p>
</article>

<!-- Widget script (place before </body>) -->
<script src="https://api.liveink.app/widget.js"
        data-key="LIK-xxxx-xxxx-xxxx"></script>

Dashboard-style data cards

<div class="dashboard">
  <div class="card">
    <h3>BTC</h3>
    <span data-liveink="bitcoin_usd"
          data-liveink-prefix="$"
          data-liveink-decimals="0">—</span>
  </div>
  <div class="card">
    <h3>ETH</h3>
    <span data-liveink="ethereum_usd"
          data-liveink-prefix="$"
          data-liveink-decimals="2">—</span>
  </div>
  <div class="card">
    <h3>EUR/USD</h3>
    <span data-liveink="eur_usd"
          data-liveink-decimals="4">—</span>
  </div>
</div>

Custom styling and no badge

<!-- Red accent, no badge, 1-minute refresh -->
<script src="https://api.liveink.app/widget.js"
        data-key="LIK-xxxx-xxxx-xxxx"
        data-refresh="60"
        data-badge="false"
        data-color="#ef4444"></script>

Italian locale formatting

<p>Il Bitcoin vale attualmente
  <span data-liveink="bitcoin_eur"
        data-liveink-prefix="€"
        data-liveink-decimals="0"
        data-liveink-locale="it-IT">…</span>.
  L'oro è a
  <span data-liveink="gold_usd"
        data-liveink-prefix="$"
        data-liveink-decimals="2"
        data-liveink-locale="it-IT"
        data-liveink-suffix=" l'oncia">…</span>.
</p>

Fallback for unavailable data

<p>Terremoto più recente:
  <span data-liveink="earthquake_latest"
        data-liveink-fallback="Nessun evento recente">Caricamento…</span>
</p>
<p>Qualità aria Roma: AQI
  <span data-liveink="aqi_rome"
        data-liveink-fallback="non disponibile">…</span>
</p>

Widget Behavior

Initialization

1. The script loads and reads configuration from data-* attributes.
2. CSS is injected for underlines, tooltips, flash animation, and the badge.
3. The API key is validated via POST /api/widget/validate.
4. If valid, the first data fetch is triggered immediately.
5. Subsequent fetches run at the data-refresh interval (default: 300s).

Update cycle

1. The widget scans the DOM for all elements with data-liveink.
2. It saves the original text content as data-liveink-original.
3. A single batch request is sent to POST /api/widget/update.
4. Returned values are formatted and injected into each element.
5. Changed values trigger a brief blue flash animation (.li-flash).

Tooltips

On hover, a tooltip shows the current value, the original value, the data source, and the last update timestamp. Tooltips follow the cursor position and appear above the element.

Styling

The widget injects minimal CSS. You can override any style with standard CSS specificity.

Default styles applied

Status attributes

The widget sets a data-liveink-status attribute on each element, which you can use to style different states:

[data-liveink-status="live"]    { color: #16a34a; }
[data-liveink-status="error"]   { color: #dc2626; opacity: 0.6; }
[data-liveink-status="loading"] { color: #94a3b8; }

Override example

/* Remove the underline */
[data-liveink] {
  border-bottom: none;
  font-weight: 700;
  color: #2563EB;
}

/* Custom flash animation */
@keyframes liFlash {
  0%   { background: rgba(34,197,94,.3); }
  100% { background: transparent; }
}

Rate Limits

Rate limits are applied per API key on a daily basis. Counters reset at midnight UTC.

Error Handling

The widget handles errors gracefully. All errors are logged to console.warn and never displayed to end users.

Subscription Plans

Support

If you need help integrating the widget or have questions about your account:

• Email: [email protected]
• Documentation: You are here!
• Test page: /test-widget — See the widget in action with a live demo
• Status page: /api/health — Check API availability

Enterprise customers have access to priority support with guaranteed 4-hour response time during business hours (CET).

© 2026 LiveInk. All rights reserved. — Back to Home