Data Aggregation

Emojis.Trade pulls live statistics for every emoji token directly from public indexers. This guide explains where the data comes from, how we query it, and best practices for performance & reliability.

---

1. Primary Source: UniSat Open API

UniSat is the first widely‑used BRC‑20 + Ordinals indexer. Core endpoint:

GET https://open-api.unisat.io/v1/indexer/brc20/<ticker>/info

Response Fields

Key	Meaning
ticker	Token identifier (may be emoji‑encoded)
max	Max supply cap
totalMinted	Total minted so far
holdersCount	Unique holder addresses
limit	Max tokens per mint op
creator	Deploying address
deployTime	ISO timestamp

💡 Some fields (e.g. volume24h) are returned only if UniSat has price data.

Auth & Rate Limits

• API key required — set header Authorization: Bearer <KEY>.

• Free tier ≈ 30 req/min. Spike beyond that → HTTP 429.

• We stagger requests 100–150 ms apart (configurable: VITE_API_STAGGER_MS).

---

2. Code Snippet

// src/lib/unisat.ts
export async function fetchInfo(tickerEncoded: string) {
  const url = `https://open-api.unisat.io/v1/indexer/brc20/${tickerEncoded}/info`;
  const res = await fetch(url, {
    headers: {
      Authorization: `Bearer ${import.meta.env.VITE_UNISAT_API_KEY}`,
      Accept: 'application/json'
    }
  });
  const json = await res.json();
  if (json.code !== 0) throw new Error(json.msg);
  return json.data;
}

fetchInfo is wrapped in SWR/React Query for caching & revalidation.

---

3. Performance Strategies

Technique	Detail
Chunked Parallelism	Fetch 10 tokens → Promise.all → 100 ms wait → next chunk.
Client Cache	SWR stale‑while‑revalidate keeps data fresh without refetch blinks.
Server Proxy (optional)	GET /api/cache/brc20/<ticker> hits a Node cache (TTL 60 s) to offload UniSat rate limits.
Conditional Fetch	Skip refetch if totalMinted hasn’t changed (ETag header planned).

---

4. Extending Data Sources

Need	API
24 h Price / Volume	OKLink BRC‑20 Tracker → /brc20/token/<ticker>
Address Portfolio	UniSat /v1/indexer/brc20/{addr}/summary
Marketplace Trades	UniSat /market/brc20/<ticker>/orders (coming soon)
Category Metadata	Static emoji-category.json or Unicode DB

Always namespace new fetchers in src/lib/ and reuse global fetch util.

---

5. Cross‑Verification

Relying on one indexer can introduce data drift. Options:

1. Dual fetch: Query a second indexer (e.g. Ordiscan) and compare totalMinted.

2. Alarm: If variance > 1 %, flag token row yellow.

3. Fallback: If UniSat 5xx for >3 s, switch UI to backup indexer.

---

6. Error Handling Pattern

try {
  const info = await fetchInfo(ticker);
  setTokenData(info);
} catch (err) {
  console.error('API error', err);
  setTokenData({ status: 'error' });
}

In the table, error rows show 🚫 “Data NA” but keep layout intact.

---

7. Security & Privacy

• API key is client‑side; use low‑priv key.

• No user PII sent — only ticker strings.

• For future private endpoints, route through serverless functions (keeps secrets on server).

---

8. Checklist Before Merging a New Fetcher

• Uses try/catch & returns fallback state

• Throttled or cached (no rapid loops)

• Adds TypeScript type for response

• Unit test passes mock JSON

• Docs updated here ✅

---

That’s the data‑pipeline in a nutshell. If you build a new integration or spot outdated endpoints, open a pull request! 🎉