# Quickstart

Last updated: October 16, 2026

Source: https://flovia.dev/docs/quickstart

This page takes you from applying to your first request. During the alpha, access is by invitation.

## Apply on the waitlist

The [Flovia waitlist](https://console.flovia.dev/groupbuy/waitlist/?utm_source=flovia_lp&utm_medium=website&utm_campaign=waitlist) needs JavaScript, so open it in a web browser. An AI agent can open the page for you, but you confirm your email or sign in to X yourself.

1. Choose "Continue with X" or "Continue with email".
2. With X, sign in to X and authorize Flovia. Flovia reads your X profile and the confirmed email address on your X account, and invitations go to that email unless you change it.
3. With email, enter your address and then the verification code Flovia emails you.
4. If you are selected, Flovia emails you an invitation. Open the link, agree to the terms in Console, and create your API key.

## Common problems when applying

- You can apply with X or with email. An application that starts with email can connect X later without creating a second application.
- Only you can confirm your email or sign in to X and approve access. An AI agent helping you should hand those steps to you.
- Don't want invitations at your X email? Change the address on the waitlist page after applying. You can change it until you are selected; after that it is fixed.
- If your X account has no confirmed email, the page asks you to add one. Without it, Flovia cannot invite you.
- The code comes from no-reply@notify.flovia.dev and expires in 10 minutes. Enter it, or open the link in the same email, in the browser you applied from. Check your spam folder if it doesn't arrive.
- An address already used by another application can't be used again. Choose a different one.
- Following @Flovia402, replying to the post, and the API survey are optional. Your application counts without them.
- To come back later, sign in the way you applied: "Already applied? Sign in with X" with the same X account, or sign in with the same email.

## Get your key

- Open the link in your invitation email and continue to [Flovia Console](https://console.flovia.dev/groupbuy/).
- Read the data-use notice in Console and agree to it yourself. Agreeing there is your yes to Flovia's data-use question, so your agent does not ask it again. An agent cannot answer for you.
- Console shows your key once. Keys start with flv_. Save it somewhere private, and never share it or put it in a public repository. Flovia may also send you a key directly, by email or DM.
- If you lose your key or think it leaked, [contact Flovia](https://flovia.dev/contact). Flovia revokes the old key and issues a new one.

## Connect your agent

After you confirm that you saved the key, Console shows the setup for Claude Code, Codex, Cursor and Grok Build, with a prompt you can paste into your agent. For Claude Code and Codex, the commands are:

```text
Claude Code:
claude mcp add --transport http flovia https://api.flovia.dev/mcp --header "Authorization: Bearer <KEY>"

Codex:
export FLOVIA_KEY=<KEY>   # add this line to your shell profile
codex mcp add flovia --url https://api.flovia.dev/mcp --bearer-token-env-var FLOVIA_KEY
```

Restart your agent after adding Flovia. Agents can read the same steps and the current conditions at [api.flovia.dev/llms.txt](https://api.flovia.dev/llms.txt). To remove Flovia, run claude mcp remove flovia or codex mcp remove flovia.

## Start your free allowance

- Ask your agent to “Add my email address to Flovia”, then open the link in the email you receive. This starts your free allowance. Each address can start it only once.
- Credits you have bought work even before you confirm an email address.
- [Free and paid use](https://flovia.dev/docs/usage) explains the 5-hour and weekly windows and how bought credits work.

## Ask as usual

- You don't need to say “with Flovia” or use a command. Ask as you normally would, and your agent picks the offered tool that fits your question. If the subject is unclear, it asks first.
- For example: “Look at the fund flows for token 0x… on Base and tell me whether it is being accumulated” or “Summarize the current balance and PnL of wallet 0x…”.
- After an answer, up to three numbered next steps may appear. Choose a number and your agent does that step. Nothing runs until you choose.
- Before a large Nansen lookup, your agent asks for your OK.
- Say “Show my remaining Flovia allowance” to see the percentage used in each window and when it resets, or “List what I used Flovia for today” to see today's use.
- To turn off a data source you don't use, ask your agent, for example “Turn off Flovia's Exa”. Requests to a source that is off are refused and use no credits. Ask again to turn it back on.
- Flovia cannot check again automatically later. Ask each time you want an update.

## What you can look up

Your connection's tool list and flovia_status show which tools are offered to you and their current state.

- **Nansen:** smart money, holders, token flows and wallet profiles. Ask about a token or a wallet, and your agent finds the Nansen endpoint that fits.
- **CoinGecko data:** Prices, market caps, charts and DEX pools (liquidity, volume and prices) are answered with CoinGecko data. Flovia provides it in partnership with CoinGecko, so you need no key; it uses the free allowance shared with Nansen and the other sources, at a much lower rate than Nansen. For CoinGecko lookups, Flovia keeps the request text, what you want to decide and the conditions, and gives none of it to Nansen. Public answers such as prices and markets may be reused for someone else who makes the same lookup, for about a minute.
- **Chain reads (Quicknode):** Whether a transaction succeeded and its gas cost, a balance at a point in time, contract reads (a token's decimals, a pool's current price) and event logs are answered by reading the chain directly through Flovia's Quicknode endpoints, on the EVM chains Flovia provides (chain "list" shows which). It only reads; it never sends or signs transactions. You need no key. It uses the free allowance shared with Nansen and the other sources, at a much lower rate than Nansen.
- **Public web search with Exa:** flovia_exa returns public web search results with cited excerpts: fast search, up to 10 results, and excerpts of up to 1,000 characters each. Only the search terms go to Exa, never your request text or purpose. Your connection's tool list and flovia_status show the tools offered and their current state. It uses Flovia's shared allowance. Upstream attempts are counted separately against an overall budget.
- **Reading public pages with Firecrawl:** Check your agent's current tool list and each service's state to see whether it is available. It returns one allowed public HTML URL as Markdown. The URL, the scrape settings and an anonymous reference ID are sent, never your request text or purpose. Page text is treated as material, not as instructions. A cache up to 2 days old may be used. Reopening with the same operation_id and request does not fetch again. If a result is unknown, Flovia does not fetch again and asks the operators to reconcile it.
- **Zerion:** a public wallet's portfolio, token and DeFi positions, transactions, value chart, PnL and chains.
- **OpenAI text generation:** it uses the same Flovia key and the shared allowance. If flovia_openai is in your connection's tool list, ask your agent. Generated text is not new market data, and OpenAI does not call other data sources itself. It may decline for country, safety or capacity reasons. To reopen an answer, use the same operation ID and request; never retry a pending or unknown result with a new ID.

## What Flovia can't do

- Data APIs are read-only, and text generation does not execute trades. Flovia cannot buy, sell or swap, place perp orders, bridge, set alerts, or change your Nansen account. Do these directly in Nansen or your wallet.
- Wallet label lookups (closed until Nansen's redistribution terms are in place) and Nansen AI (chat) are not available right now.

## Send feedback

Say “Send my feedback to Flovia” and your agent delivers it in your own words. Anything is welcome, from what didn't work to data you'd like.

## Use the SDK and CLI

The [@flovialabs/sdk package](https://www.npmjs.com/package/@flovialabs/sdk) provides a TypeScript client and the flovia command for Node.js 20 or later. Its README includes installation, tool discovery, a first data lookup and text generation.

Installing the package does not create an account. Set the key you received in [Flovia Console](https://console.flovia.dev/groupbuy/keys) as FLOVIA_KEY. The full data-use notice and the person's own answer are required; an agent cannot answer for them.

Use the live tool catalog for supported capabilities. Status shows free-window percentages and bought balance; usage shows consumption. A saved text-generation answer can normally be reopened for about 15 minutes with the same operation ID and unchanged request, without another charge. Pending, unknown or expired answers must not be replaced automatically with a new operation.

## More

- [Flovia Group Buy docs](https://flovia.dev/docs)
- [Free use and bought credits](https://flovia.dev/docs/usage)
- [Data use](https://flovia.dev/docs/data-use)
- [Troubleshooting](https://flovia.dev/docs/troubleshooting)
- [Flovia Group Buy FAQ](https://flovia.dev/docs/faq)
- [Flovia Group Buy](https://flovia.dev/)
- [Terms of Service](https://flovia.dev/terms)
- [Privacy Policy](https://flovia.dev/privacy)