crypto-rag: a keyless Indonesian crypto assistant that keeps market numbers out of the vector store

The problem crypto-rag solves, and who actually needs it

Most crypto chatbots fail in one of two directions. Either they answer from a frozen corpus and quote a price from training time, or they fetch live numbers and then let a language model paraphrase them into something wrong. crypto-rag takes a position on this: the README states the core principle directly, that market numbers should never sit in a vector store because they go stale instantly. Numeric data (price, funding, TVL) is fetched live at query time through a tool call. RAG is reserved for concepts, descriptions, and static context. The README claims numbers never pass through the LLM, which is what makes the price answers free of hallucination.

The audience is narrow and specific. The knowledge corpus is Indonesian, the chat examples are Indonesian, and the project describes itself as an Indonesian-language crypto assistant. If you are building for English-speaking users, the retrieval half of this project gives you nothing without a corpus swap. If you are building for Indonesian users who ask concept questions alongside price questions in the same session, the split between static retrieval and live tool calls is the design worth copying.

The project needs no API key for market data. That matters for anyone prototyping without wanting to register with six exchanges.

Router, RRF, and why numbers bypass the LLM

The README's architecture diagram shows a router at the front that detects intent, then dispatches down one of six paths. Concept and education questions go to the knowledge corpus in FAISS. Realtime price questions go to six exchanges plus a Binance WebSocket. Derivative and funding questions go to Binance Futures. TVL and on-chain questions go to DefiLlama. Sentiment goes to the Fear & Greed Index. Market cap and category questions go to a static coin corpus, also in FAISS, combined with Reciprocal Rank Fusion.

Retrieval inside the RAG path is hybrid. BM25 handles keyword matching, dense embeddings handle semantic matching, and Reciprocal Rank Fusion merges the two ranked lists. A cross-encoder reranker is available behind the --rerank flag, which the README describes as more precise and slower. That is an honest trade-off statement, and it is the right default: reranking every query doubles latency for a gain that only shows up on ambiguous queries.

The agent path is separate. For complex or multi-step queries, the tool-calling agent lets the LLM choose which tools to call, with the README's examples being comparing funding between BTC and ETH, or finding which DeFi coin has the highest funding. This is where the architecture gets interesting and also where it gets fragile: an LLM choosing tools means the routing decision is no longer deterministic, and the README does not document what happens when the model picks the wrong tool.

LLM synthesis is optional throughout. Without configuration, the system falls back to extractive answers. That fallback is the reason the project is usable at all on a fresh clone.

Installing crypto-rag and running a first real query

The README gives a virtualenv-based setup with five pip packages: requests, numpy, faiss-cpu, fastembed, and websocket-client. There is no pyproject.toml or requirements.txt in the top-level repository listing, so the install line in the README is the install path.

python3 -m venv venv
venv/bin/pip install requests numpy faiss-cpu fastembed websocket-client

After that you build the data and the indexes. This runs once, and the README marks it as such. fetch_data.py pulls coin data from CoinGecko, index.py builds the coin embedding and FAISS index, and knowledge_index.py builds the knowledge corpus index.

venv/bin/python fetch_data.py
venv/bin/python index.py
venv/bin/python knowledge_index.py

Optionally, enrich_categories.py adds per-category tags from CoinGecko, and index.py has to be rebuilt afterward for the new categories to take effect. The README's example uses --pages 1.

venv/bin/python enrich_categories.py --pages 1
venv/bin/python index.py

Now the first real use. Running rag.py with no arguments drops into interactive chat mode, which carries follow-up memory. The README's session shows a concept question, then a price question that resolves the pronoun automatically, then a trend question that does the same.

venv/bin/python rag.py
#   > apa itu Bitcoin
#   > berapa harganya sekarang
#   > tren nya seminggu terakhir
#   > keluar

For a one-shot query, pass the question as an argument. Adding --live attaches sub-second Binance WebSocket prices to the realtime answer.

venv/bin/python rag.py "harga BTC sekarang"
venv/bin/python rag.py --live "harga SOL"

To enable LLM synthesis, copy config.example.json to config.json and fill in the key. The README's example points at a StepFun endpoint, but any OpenAI-compatible endpoint works, including Groq, LM Studio, and Ollama.

{
  "OPENAI_BASE_URL": "https://api.stepfun.ai/step_plan/v1",
  "OPENAI_API_KEY": "your-key",
  "OPENAI_MODEL": "step-3.5-flash"
}

The environment variables OPENAI_BASE_URL, OPENAI_API_KEY, and OPENAI_MODEL are also supported and take precedence over config.json. Skip this entirely and the system still answers, extractively.

Where crypto-rag is the wrong tool

The extractive fallback is not a degraded version of the synthesized answer. It is a different kind of answer. If you configure no LLM, you get retrieved passages and live data stitched together, without the natural-language synthesis the project is named for. Anyone evaluating crypto-rag on a fresh clone without config.json is evaluating half the system.

Keyless market data has a cost the README does not discuss. Six exchange public endpoints, Mempool.space, DefiLlama, and CoinGecko's free tier all have rate limits and no availability guarantee. The README does not document retry behaviour, backoff, or what the router does when one of the six exchanges is unreachable during a cross-exchange price comparison. There is a cache.py in the repository listing, and fetch_data.py has a --fresh flag to force refetch even when the cache is still fresh, but the README does not describe cache expiry semantics for live price calls.

The corpus is Indonesian. Retrieval quality on an English question is not something the README addresses, and a hybrid BM25 plus dense retrieval stack tuned on Indonesian text will not transfer cleanly.

The routing layer is the real risk surface. Concept questions and price questions look similar in short form, and the router decides before retrieval happens. The README does not document router accuracy, misroute handling, or how to force a path other than through the --realtime flag. If you need deterministic behaviour, this design gives you a probabilistic component at the front door.

Finally, there is no server mode. The repository listing shows rag.py, agent.py, market.py, and the rest as scripts. There is no FastAPI app, no Dockerfile, and no HTTP interface. Embedding this into a product means writing that layer yourself.

crypto-rag versus a plain LLM with a price API

The obvious alternative is a general-purpose LLM with a price API bolted on through function calling. The difference is where the grounding happens. In that setup, the model receives a price as a tool result and then writes a sentence containing it. The number passes through the model's output layer, and any paraphrase, rounding, or unit confusion is the model's to introduce. crypto-rag's stated design keeps numbers out of the LLM entirely: the router fetches them, and synthesis, when enabled, works from grounded context with citations and a timestamp.

The second difference is the corpus. A general LLM already knows what impermanent loss is. crypto-rag retrieves an Indonesian-language explanation from a tagged corpus of 146-plus topics, which means the answer's framing is controllable and the citation is inspectable. That is a real advantage for anything regulated or audited, and it is also a maintenance burden: someone has to keep that corpus current.

The third difference is breadth of data sources. A price API gives you price. crypto-rag's README lists funding rate and open interest from Binance Futures, per-protocol and per-chain TVL from DefiLlama, the Fear & Greed Index, Bitcoin fee and mempool data from Mempool.space, Ethereum EIP-1559 gas, stablecoin supply, 24-hour DEX volume, and Solana supply, epoch, and inflation figures. Assembling that yourself is several integrations, each with its own key or lack thereof.

Where the plain-LLM approach wins is latency and predictability. One API call beats a router, a retrieval pass, and a tool call. crypto-rag trades that latency for inspectable grounding.

Maintenance cost, licence, and what the README leaves open

The last push to the repository was on 2026-09-07, and the repository is not archived. The README documents no releases, so there is no versioned upgrade path to follow. Upgrading means pulling master and re-running the three index scripts when the corpus or the coin data changes, since the FAISS indexes are built artifacts, not shipped files.

The recurring cost is the corpus. A 146-topic Indonesian knowledge base covering concepts, technology, categories, trading, risk, protocols, strategy, history, networks, security, metrics, ecosystems, regulation, and advanced protocols does not stay accurate on its own, and the README describes no contribution process or content review step. The coin data has a similar shape: fetch_data.py pulls from CoinGecko, and enrich_categories.py tags 615 coins, but nothing in the README describes a scheduled refresh.

The licence is MIT. That permits commercial use, modification, and redistribution provided the copyright notice and permission notice are included. It offers no patent grant and no warranty, and it says nothing about the terms of the upstream data sources, which are separate from the code licence. CoinGecko, DefiLlama, Mempool.space, and the six exchanges each have their own terms, and nothing in the README addresses them. That is a question for your own review, not a legal conclusion.

The README does not document rollback, error handling on upstream failure, or the cache expiry policy for live prices. Those are the gaps to close before depending on it.

Editorial conclusion

Adopt crypto-rag if you need Indonesian-language crypto answers that cite live numbers, and you are willing to run three index-building scripts and accept keyless public endpoints with no SLA. Skip it if you need a hosted API, a web UI, or a corpus in another language: the README describes a CLI, and the knowledge corpus is written in Indonesian. Before trusting an answer, run venv/bin/python eval_rag.py against the 87-query golden set, and check whether your query actually routed to the live path rather than the static corpus.

Frequently asked questions

Official sources

1. iamzulx/crypto-rag on GitHub
2. Issues
3. License: MIT
4. README