📘 Price Fetcher API Documentation

---

1. Overview

The Price Fetcher API provides real-time price data (cached per CACHE_TTL_SECONDS) for a wide range of cryptocurrencies and fiat currencies. It fans out concurrently to Binance, OKX, Kraken, Coinbase, and MEXC, falling back to CoinGecko only when no primary source returns a price. When no direct pair is available on any exchange, the API derives a price through an intermediate asset (e.g., RTM → USDT → IDEX).

The returned price is the consensus value — the source whose price is closest to the median of all responding sources — which is robust to a single outlier or stale feed.

🔑 Key Features

• ✅ Crypto-to-Fiat Conversion — e.g. BTC → USD
• ✅ Fiat-to-Fiat Conversion — e.g. PLN → UAH
• ✅ Crypto-to-Crypto Conversion — e.g. ETH → BTC
• ✅ Multi-exchange parallel fetch with in-flight request deduplication
• ✅ Median-consensus price selection (outlier-resistant)
• ✅ Automatic inversion for pairs quoted in the opposite direction
• ✅ Smart caching with per-result TTL, plus separate transient vs. permanent failure TTLs
• ✅ Derived pricing via an intermediate (e.g. FIRO → USDT → PLN)
• ✅ Minimal output via fields and raw scalar output via format=raw

---

2. Query Parameters

🔹 Required

Parameter	Description	Example
token	Asset you're pricing (crypto or fiat)	BTC, ETH, USD

🔹 Optional

Parameter	Description
quote	Currency the price is quoted in. Defaults to DEFAULT_QUOTE env (USDT).
source	Restrict to a specific source: binance, okx, kraken, coinbase, mexc, coingecko, or derived.
intermediate	Intermediate asset to use for derived pricing. Defaults to INTERMEDIATE_SYMBOL env (USDT).
fields	Comma-separated fields to include in the response (e.g. price,source).
format	Set to raw to return a single field as plain text (scalar) instead of JSON. Requires exactly one scalar field in fields.

---

3. Response Format

Example full response

{
  "symbol": "ETH",
  "quote": "USDT",
  "price": 1598.025,
  "source": "coinbase",
  "inverted": false,
  "expires_in": 299.18,
  "expires_at": "2026-04-15T21:47:39.767047",
  "sources": [
    {"source": "binance",  "price": 1597.49,  "inverted": false, "expires_in": 298.57, "expires_at": "..."},
    {"source": "okx",      "price": 1597.69,  "inverted": false, "expires_in": 298.87, "expires_at": "..."},
    {"source": "kraken",   "price": 1600.00,  "inverted": false, "expires_in": 299.18, "expires_at": "..."},
    {"source": "coinbase", "price": 1598.025, "inverted": false, "expires_in": 299.48, "expires_at": "..."},
    {"source": "mexc",     "price": 1597.48,  "inverted": false, "expires_in": 299.99, "expires_at": "..."}
  ]
}

Derived responses additionally include a components array with each leg:

"components": [
  {"pair": "RTM/USDT",  "source": "mexc",    "price": 0.00123, "inverted": false, "expires_in": 287.2, "expires_at": "..."},
  {"pair": "IDEX/USDT", "source": "binance", "price": 0.0456,  "inverted": false, "expires_in": 287.2, "expires_at": "..."}
]

Field descriptions

Field	Description
symbol	Base token being priced
quote	Currency the price is quoted in
price	Consensus price (source closest to the median)
source	Exchange providing the consensus price (derived if computed via intermediate)
inverted	true if the original pair was fetched reversed and then inverted
expires_in	Seconds until the cached value expires
expires_at	ISO timestamp when the cached value expires
sources	All contributing source prices
components	(Derived only) The two legs used to compute the price

---

4. Usage Examples

Base URL used below: https://price-fetcher.89.167.6.211.sslip.io

➤ Basic query

curl "https://price-fetcher.89.167.6.211.sslip.io/price?token=BTC&quote=USDT"

➤ Specific source only

curl "https://price-fetcher.89.167.6.211.sslip.io/price?token=ETH&quote=USDT&source=binance"

➤ Derived pricing via an intermediate

curl "https://price-fetcher.89.167.6.211.sslip.io/price?token=RTM&quote=IDEX&intermediate=USDT"

➤ Return only selected fields (JSON)

curl "https://price-fetcher.89.167.6.211.sslip.io/price?token=ETH&quote=BTC&fields=price,source"

➤ Return a raw scalar (plain text, not JSON)

curl "https://price-fetcher.89.167.6.211.sslip.io/price?token=BTC&quote=USDT&fields=price&format=raw"
# → 73925.6

➤ Health check

curl "https://price-fetcher.89.167.6.211.sslip.io/health"

---

5. Google Sheets Integration

Use the raw format so the cell receives a pure number:

=IMPORTDATA("https://price-fetcher.89.167.6.211.sslip.io/price?token=ETH&quote=BTC&fields=price&format=raw")

---

6. Python Integration

import requests

url = "https://price-fetcher.89.167.6.211.sslip.io/price"

# Full JSON response
res = requests.get(url, params={"token": "BTC", "quote": "USDT"})
print(res.json())

# Scalar only
price = float(requests.get(url, params={
    "token": "BTC", "quote": "USDT",
    "fields": "price", "format": "raw",
}).text)
print(price)

---

7. Supported Sources

Source	Description
binance	Binance spot market
okx	OKX spot market
kraken	Kraken (auto-maps BTC→XBT, DOGE→XDG)
coinbase	Coinbase spot (tries inverted pair on 404)
mexc	MEXC global spot
coingecko	CoinGecko aggregator — used only as fallback
derived	Computed via an intermediate asset, e.g. A→USDT→B

---

8. Error Handling

Status	Condition
400	Invalid source specified — unknown source value
400	format=raw requires exactly one field
400	format=raw only supports scalar fields
404	No price data available — no exchange returned a usable price and no derivation was possible
404	No data found for <source> on <BASE>/<QUOTE> — pinned source has no data for that pair

---

9. Configuration (Environment Variables)

Variable	Default	Description
CACHE_TTL_SECONDS	300	TTL for successful price results
FAILURE_TTL_TRANSIENT	60	Back-off for timeouts / 5xx / network errors
FAILURE_TTL_PERMANENT	3600	Back-off when a pair is unsupported on an exchange
COINGECKO_LIST_TTL	86400	TTL for the CoinGecko coins/list cache
DEFAULT_QUOTE	USDT	Default quote when not provided
INTERMEDIATE_SYMBOL	USDT	Default intermediate asset for derived pricing
HTTP_TIMEOUT	5	httpx client timeout (seconds)

---

10. Deployment

Docker Compose

git clone <your-repo-url>
cd <repo-dir>
docker compose build
docker compose up -d
# Shutdown:
docker compose down

Helm (Kubernetes)

A Helm chart is provided under price-fetcher/. Key values:

• image.repository / image.tag — container image to deploy
• ingress.hosts[].host and ingress.tls[] — hostname and TLS secret
• ingress.annotations — e.g. cert-manager.io/cluster-issuer: letsencrypt-http

Install or upgrade:

helm -n price-fetcher upgrade -i --create-namespace price-fetcher ./price-fetcher

---

11. ❤️ Support the Project

This service is free, but if you'd like to help with hosting or development:

💸 Donation Wallets

• Solana (SOL) GTsL1ZJqHthtdDLSKJt4D6x4a52NoHEG7tMtWeg1kCjK

• Ethereum / Polygon (ETH/POL) 0xa9Ce7AD40027a80C2EEf3475CcCc6b0B22f1Ed6D

Even small contributions help — thank you! 🙏