# Flovia

> Flovia lets your Claude Code or Codex agent read real Nansen, CoinGecko and on-chain data through one MCP connection, and generate text with OpenAI when offered. Use within the free allowance is free; Nansen lookups share your requests and Nansen's answers with Flovia and Nansen. Data tools only read and text generation executes no trading, swaps, orders or wallet actions.

Flovia is in alpha: tools, limits and prices may change without notice; check flovia_status (recent_updates) for what changed.

Condition of use: Flovia collects how you use its data lookups (what you ask, each lookup and how your agent calls Flovia) and uses it as data. The full notice also covers OpenAI text processing and retention below. You agree to it once, in the Console, before your key is shown; that is your y, and chat does not ask again. A key that has not answered the current notice is asked once, at its first lookup, and never again; only your own answer counts. With n, lookups and generation stop and your referral code is paused; nothing else is deleted, and you can answer y later. Read the full notice in the Console, or ask your agent what Flovia shares; this page is a summary.
Flovia is not available in sanctioned regions.

## Connect

- Get a key: accept your Waitlist invitation, open the Flovia Console (https://console.flovia.dev/groupbuy/), agree to what is shared and save the key shown once. Keys start with flv_; keep yours private.
- Claude Code plugin (flovia@flovia): save the key in a file, run /flovia:setup and give it the file's path; it checks the key and connects Flovia.
- Claude Code: claude mcp add --transport http flovia https://api.flovia.dev/mcp --header "Authorization: Bearer <KEY>"
- Codex: export FLOVIA_KEY=<KEY>, then codex mcp add flovia --url https://api.flovia.dev/mcp --bearer-token-env-var FLOVIA_KEY
- Ask normally (e.g. "Is token 0x... on Base being accumulated?"). You need not name Flovia or use a slash command; choose offered tools by the question. Consent, service settings and cost confirmations still apply.

## Tools

- flovia_endpoints: find the Nansen endpoint for a question, with its size and required fields (pass question; or category and page to browse one category, 10 per page).
- flovia_nansen: fetch Nansen data (smart money, holders, token flows, wallet profiles).
- flovia_coingecko: prices, market caps, charts and DEX pools from CoinGecko.
- flovia_quicknode: raw EVM chain reads (Ethereum, Base, Arbitrum, BNB and others: transactions, balances, contract reads, logs).
- flovia_exa: public web search, with source URLs and excerpts.
- flovia_firecrawl: one allowed public HTML documentation URL as Markdown; list gives hosts. No private pages or automatic crawling.
- flovia_zerion: a public wallet's portfolio, token and DeFi positions, transactions (one page), value chart, PnL and chains; list shows actions.
- flovia_openai (alpha; may change) generates or transforms text with gpt-6-luna; its text is not market data. Save operation_id before sending; if a result is pending or unknown, keep that id and never send again with a new one. With an OpenAI SDK, set max_retries=0. Use the same Flovia key; current consent, a supported location, safety checks and capacity still apply.
- flovia_status: how much of your free 5-hour and weekly windows is used (%), when each resets, bought credits and recent changes.
- flovia_usage_today: your data lookups today (or since a time within the last 7 days), with text generations counted separately in generations. Its items list 20 generation records per page; pass generations.next_cursor as generation_cursor for more.
- flovia_email: your optional email address and which Flovia mail you want. Confirming an address starts your free allowance.
- flovia_services: turn a data service on or off for yourself (the plugin's /flovia:services); a service that is off refuses its calls and uses no credits.
- flovia_lookup: an earlier lookup again by its lookup id, free: a Nansen answer as stored; for the other sources the answer for about 15 minutes after the lookup (only for that user), then only the record. Use openai:<generation_id> from generations.items for a saved text answer, without its original input. Expired, pending or unknown records never start a new generation.
- Pass a stable optional operation_id per question; retrying with it never charges twice. After a restart, list flovia_usage_today with conversation and reopen lookups with flovia_lookup instead of asking again.
- flovia_feedback, flovia_feedback_status: send feedback in your words and see what happened to it.
- flovia_case_report: optionally submit your final/partial answer and end declaration for Flovia's internal verification, only after this report's separate explicit opt-in. It never collects host conversations automatically or shares the report with providers or training; get/delete your own receipt.
- flovia_data_consent: record your own y or n to the data-use question (y turns lookups on, n stops them and pauses your referral code).
- flovia_console_link: only when you ask to connect an existing Flovia key to Console. Give its private short-lived code only to its owner for the Console form; operator verification is required before linking.
- flovia_stop_sharing: stop sharing (lookups stop).

## Combine data and text

Optional flovia_openai uses: CoinGecko: market notes; Nansen: wallet/flow reports; QuickNode: EVM transaction explanations; Exa: source comparisons. Use your own answer if enough. Generate only if the user chooses; send only permitted summaries with sources, units, times and gaps; verify arithmetic. After answering: ask at most once per task if helpful/missing; skip if declined/replay. Only their words, only if they want to share: flovia_feedback about ["openai:<generation_id>"]. Never infer satisfaction.
Use one conversation_id for the task's data and generation; a client threadId/sessionId overrides it. Filter flovia_usage_today by the returned conversation. If the user wants to report the answer, get flovia_case_report's separate opt-in first and use that conversation as case_label. Never report automatically. These labels and a completed response do not prove the user's goal was met.

## Prices

- Nansen, CoinGecko, QuickNode, Exa, Firecrawl, Zerion and OpenAI share one free Flovia allowance per user, like Claude's usage limits: a 5-hour window and a weekly window, each starting with your first free use after the last one ended. Whichever reaches 100% first pauses free use until it resets. It starts once you confirm an email address (flovia_email; once per address). flovia_status shows the percent used of each window and when it resets. Provider capacity and rate limits may stop a request even when the windows have room.
- A single large call can use the week even when the 5-hour window is full. Sources you do not use cost nothing, and a reused answer is free. Bought credits pay for any source when the free allowance cannot cover a call.
- If a data source says it is busy, does not answer or fails on its side, the lookup costs nothing. A lookup the source rejects because of the request itself (such as a wrong address) may still cost credits. If Flovia cannot tell whether a lookup ran, it may count its usual cost. Do not retry automatically.
- Buying Flovia credits is paused for now, during the alpha's first wave. Free use and existing balances are unchanged. Flovia is in alpha, so this may change. Bought credits are shown in US dollars (e.g. $4.20 left), do not expire and unused ones are refunded on request.

## Sharing and retention

- Nansen lookups share your request, its purpose, the endpoint and conditions, and Nansen's answer, with Flovia and Nansen. Nansen receives the endpoint and conditions with each lookup it fetches; Flovia may give Nansen the rest. Details: https://flovia.dev/docs/connection
- CoinGecko, QuickNode and Exa: Flovia keeps the request, purpose and conditions and gives none of it to Nansen. Public CoinGecko and QuickNode answers (prices, markets, block data) may be reused for others who ask the same, for about a minute at most; never an answer about a wallet or a transaction. Otherwise Flovia stores no answers from these three. If a reply does not reach you, you can usually fetch that answer yourself for about 15 minutes; only you can, and after that Flovia can no longer return it. CoinGecko and QuickNode receive only the lookup itself (a coin, an address, a method or a search term, with its conditions), never your request text or its purpose. Exa receives only the public search query and search settings.
- Exa may use search queries to improve its service, including model training, under its terms and privacy policy. Do not put personal information or secrets in a search.
- Firecrawl sharing and retention: only the allowed public HTML URL, scrape settings and an anonymous reference ID go to Firecrawl, never your request text or purpose. Flovia keeps the reply for you alone for about 15 minutes, and the request, purpose, URL and settings for 2 years (30 days after you stop sharing); none goes to Nansen. Firecrawl uses its normal index/cache, without ZDR, in the US; its deletion deadline and no-training guarantee are unconfirmed. A cache freshness setting of up to 2 days is not a deletion deadline. A clear upstream refusal costs nothing; an uncertain result holds the reservation for reconciliation and is not automatically resent.
- Zerion: only the public wallet address and filters go to Zerion, never your request text or purpose. Flovia keeps the address with the lookup's record for 2 years (30 days after you stop sharing), never shares Zerion's answers and gives none to Nansen.

- OpenAI text generation: your text and a Flovia-derived account identifier (not your name, email or key) go to OpenAI for safety checking and generation. OpenAI does not use them for training, but may keep them for up to 30 days to monitor abuse. Flovia keeps no input text: only a keyed retry fingerprint for 90 days, your reply for you alone for about 15 minutes, and counts and costs. Safety refusals generate and charge nothing; Flovia records only the event and time, kept 30 days or until a stop is lifted. Three in 24 hours stop your new generation until operator review, even after you stop sharing. Generated text is not market data and does not call other providers.
- Never put keys, recovery phrases or passwords in a request; Flovia refuses them and does not store them.
- Data-lookup request texts, purposes, stored Nansen answers, wallet addresses and feedback are kept for 2 years for analysis during the alpha, then deleted (30 days after you stop sharing; records made before the current notice keep 90 days). OpenAI input and replies follow the separate terms above. Details: https://flovia.dev/docs/connection