# Authentication

> How to authenticate to the f1ow MCP server and API — OAuth 2.1 for Claude and ChatGPT, API keys for code and editors, and x402 pay-per-call for autonomous agents.

Source: https://www.f1ow.com/docs/auth

Every tool is reachable four ways. Pick the one that fits your client:

| Method | Best for | Account |
| --- | --- | --- |
| [OAuth 2.1](#oauth) | Claude, ChatGPT, MCP clients with a sign-in flow | yes |
| [API key](#api-keys) | Cursor, VS Code, your own code, bots | yes |
| [Key in path](#key-in-path) | Clients that cannot send headers | yes |
| [x402](#x402) | Autonomous agents with a wallet | no |

OAuth and API keys draw on the same account, subscription and call balance.

## OAuth

f1ow is an OAuth 2.1 authorization server for the MCP endpoint https://mcp.f1ow.com/mcp. A client that supports MCP authorization needs only that URL. It will:

1. receive a `401` with protected-resource metadata (RFC 9728) pointing at `https://www.f1ow.com`,
2. read the authorization-server metadata (RFC 8414) and register itself (dynamic client registration, RFC 7591),
3. send you through sign-in and consent (authorization code with PKCE S256),
4. receive a short-lived access token and a rotating refresh token.

You sign in with any method the site supports. Every token maps to the same account. Revoke a client at any time under *Connected apps* in the dashboard.

| Metadata | URL |
| --- | --- |
| Protected resource | `https://mcp.f1ow.com/.well-known/oauth-protected-resource` |
| Authorization server | `https://www.f1ow.com/.well-known/oauth-authorization-server` |
| JWKS | `https://www.f1ow.com/.well-known/jwks.json` |

## API keys

Create keys in the [dashboard](https://www.f1ow.com/dashboard). A key is shown **once**; only a hash is stored. Send it as a bearer token:

```http
Authorization: Bearer <your-key>
```

The same header works on the MCP endpoint https://mcp.f1ow.com/, the [REST API](https://www.f1ow.com/docs/api/rest) and the [WebSocket](https://www.f1ow.com/docs/api/websocket) handshake. An OAuth access token works in its place on all three.

Use one key per client or bot, so each has its own usage history and you can revoke one without touching the others.

## Key in path

Some clients can only take a URL. Put the key in the path instead:

```text
https://mcp.f1ow.com/key/<your-key>          MCP
https://mcp.f1ow.com/key/<your-key>/v1       REST
wss://mcp.f1ow.com/key/<your-key>/v1/ws      WebSocket
```

The URL is now a credential. Don't paste it anywhere you wouldn't paste the key.

## x402

[x402](https://www.x402.org) lets an agent pay per call over HTTP, with no account, key or subscription. f1ow accepts **USDC on Base**.

The payment exchange depends on the transport:

- **REST:** call a priced resource under `https://mcp.f1ow.com/x402/v1`. The server answers HTTP `402 Payment Required` with a base64 `PAYMENT-REQUIRED` header describing the price, asset and pay-to address. Sign the payment and retry with a `PAYMENT-SIGNATURE` header. A successful paid response includes a base64 `PAYMENT-RESPONSE` receipt header.
- **MCP:** call a priced tool at https://mcp.f1ow.com/x402. The server answers HTTP `200` with a JSON-RPC tool result whose `isError` is `true`; the payment challenge is in `structuredContent` and JSON text in `content`. Sign the payment and retry the tool call with the payment object in `params._meta["x402/payment"]`. A successful paid result carries its receipt in `result._meta["x402/payment-response"]`. The MCP endpoint also supports the same payment headers as REST.

The server runs the tool before settling and does not settle a failed tool call. Use an x402 client that supports your chosen transport to automate the exchange. Prices per call:

| Tool | Price per call |
| --- | --- |
| [UTC Anchor](https://www.f1ow.com/docs/tools/utc_time) `utc_time` | free |
| [Fear & Greed](https://www.f1ow.com/docs/tools/sentiment_fear_greed) `sentiment_fear_greed` | $0.005 |
| [Trending](https://www.f1ow.com/docs/tools/market_trending) `market_trending` | $0.005 |
| [Candles](https://www.f1ow.com/docs/tools/market_candles) `market_candles` | $0.01 |
| [Coin Details](https://www.f1ow.com/docs/tools/market_coin_details) `market_coin_details` | $0.01 |
| [Crypto Calendar](https://www.f1ow.com/docs/tools/catalysts_calendar) `catalysts_calendar` | $0.01 |
| [ETF Flows](https://www.f1ow.com/docs/tools/catalysts_etf_flows) `catalysts_etf_flows` | $0.01 |
| [Exchange Listings](https://www.f1ow.com/docs/tools/catalysts_exchange_listings) `catalysts_exchange_listings` | $0.01 |
| [Funding](https://www.f1ow.com/docs/tools/funding_current) `funding_current` | $0.01 |
| [Implied Volatility](https://www.f1ow.com/docs/tools/options_volatility) `options_volatility` | $0.01 |
| [Macro Calendar](https://www.f1ow.com/docs/tools/catalysts_economic_calendar) `catalysts_economic_calendar` | $0.01 |
| [Market Overview](https://www.f1ow.com/docs/tools/market_overview) `market_overview` | $0.01 |
| [On-Chain Metrics](https://www.f1ow.com/docs/tools/onchain_metrics) `onchain_metrics` | $0.01 |
| [Open Interest](https://www.f1ow.com/docs/tools/derivatives_open_interest) `derivatives_open_interest` | $0.01 |
| [Options Chain](https://www.f1ow.com/docs/tools/options_chain) `options_chain` | $0.01 |
| [Options-Implied Odds](https://www.f1ow.com/docs/tools/options_probability) `options_probability` | $0.01 |
| [Order Book](https://www.f1ow.com/docs/tools/flow_orderbook) `flow_orderbook` | $0.01 |
| [Perp Flow](https://www.f1ow.com/docs/tools/derivatives_flow) `derivatives_flow` | $0.01 |
| [Prediction Odds](https://www.f1ow.com/docs/tools/events_prediction_odds) `events_prediction_odds` | $0.01 |
| [Regulatory Filings](https://www.f1ow.com/docs/tools/filings_search) `filings_search` | $0.01 |
| [Social Sentiment](https://www.f1ow.com/docs/tools/sentiment_social) `sentiment_social` | $0.01 |
| [Spot & Perp Quotes](https://www.f1ow.com/docs/tools/market_quotes) `market_quotes` | $0.01 |
| [Top Movers](https://www.f1ow.com/docs/tools/market_top_movers) `market_top_movers` | $0.01 |
| [Coin Universe](https://www.f1ow.com/docs/tools/market_coins) `market_coins` | $0.01 |
| [Bulk History](https://www.f1ow.com/docs/tools/market_history) `market_history` | $0.02 |
| [Liquidation History](https://www.f1ow.com/docs/tools/derivatives_liquidations) `derivatives_liquidations` | $0.02 |
| [Options Positioning](https://www.f1ow.com/docs/tools/options_positioning) `options_positioning` | $0.02 |
| [Technicals](https://www.f1ow.com/docs/tools/ta_technicals) `ta_technicals` | $0.02 |
| [Whale Context](https://www.f1ow.com/docs/tools/flow_whale_context) `flow_whale_context` | $0.02 |
| [Whale Positions](https://www.f1ow.com/docs/tools/flow_whale_positions) `flow_whale_positions` | $0.02 |
| [Gamma & Hedge Scenarios](https://www.f1ow.com/docs/tools/options_gamma) `options_gamma` | $0.03 |
| [Perp Price Levels](https://www.f1ow.com/docs/tools/flow_levels) `flow_levels` | $0.03 |
| [Market Regime](https://www.f1ow.com/docs/tools/research_regime) `research_regime` | $0.05 |
| [News](https://www.f1ow.com/docs/tools/news_search) `news_search` | $0.05 |
| [Opportunity Scan](https://www.f1ow.com/docs/tools/research_opportunities) `research_opportunities` | $0.05 |
| [Positioning](https://www.f1ow.com/docs/tools/research_positioning) `research_positioning` | $0.05 |
| [Trade Plan Review](https://www.f1ow.com/docs/tools/research_trade_plan) `research_trade_plan` | $0.05 |
| [Token Dossier](https://www.f1ow.com/docs/tools/research_token_view) `research_token_view` | $0.07 |
| [Tweet Search](https://www.f1ow.com/docs/tools/sentiment_twitter) `sentiment_twitter` | $0.10 |

WebSocket is not available over x402. For sustained use, a subscription is far cheaper per call. See [pricing & limits](https://www.f1ow.com/docs/pricing-limits).

## Errors

| Status | Meaning |
| --- | --- |
| `401` | No credential, or an unknown one. MCP clients start OAuth from here. |
| `402` | REST: x402 payment required, or the metered account's period or call balance is used up. A metered denial links to the dashboard. |
| `403` | The credential was rejected. |

REST errors are [RFC 9457 problem details](https://www.f1ow.com/docs/api/rest#errors).
MCP payment challenges and metered-usage denials are HTTP `200` tool results with `isError: true`, not HTTP `402` responses.