# REST API

> The f1ow crypto market data REST API — every MCP tool as an HTTP resource with JSON responses, bearer or x402 auth, an OpenAPI 3.1 spec and RFC 9457 errors.

Source: https://www.f1ow.com/docs/api/rest

Every f1ow tool is also a REST resource. The tools, credentials and balance are the same as over MCP, so there is no MCP client to run.

| Endpoint | URL |
| --- | --- |
| REST · Bearer | `https://mcp.f1ow.com/v1` |
| REST · x402 | `https://mcp.f1ow.com/x402/v1` |
| REST · Key in path | `https://mcp.f1ow.com/key/<your-key>/v1` |
| WebSocket · Bearer | `wss://mcp.f1ow.com/v1/ws` |
| WebSocket · Key in path | `wss://mcp.f1ow.com/key/<your-key>/v1/ws` |
| OpenAPI spec | `https://mcp.f1ow.com/openapi.json` |
| AsyncAPI spec | `https://mcp.f1ow.com/asyncapi.json` |

## A request

```bash
curl "https://mcp.f1ow.com/v1/derivatives/funding/BTC" \
  -H "Authorization: Bearer $F1OW_API_KEY"
```

Path segments and query parameters map one-to-one to the tool's arguments. Arrays are comma-separated (`?symbols=BTC,ETH`). The trade-plan check takes a JSON body:

```bash
curl -X POST "https://mcp.f1ow.com/v1/research/trade-plan" \
  -H "Authorization: Bearer $F1OW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"BTC","entry":70000,"stop":68000,"target":75000,"account_size":10000,"risk_percent":1}'
```

Each [tool page](https://www.f1ow.com/docs/tools) lists its path, parameters and ready-to-run cURL, TypeScript and Python examples.

## Responses

The body is the tool's JSON result, typed per tool in the OpenAPI spec:

```json
{
  "symbol": "BTC",
  "...": "the tool's fields",
  "generatedAt": "2026-11-07T15:36:14Z"
}
```

- Every tool returns a JSON object. The fields are documented on its [tool page](https://www.f1ow.com/docs/tools).
- `generatedAt` is when the data was produced, from the source's timestamp where it has one.
- There is no text report here. The model-readable report is MCP-only: connect over [MCP](https://www.f1ow.com/docs/connect/custom-agent) to get it next to the same JSON.

## Errors

Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details (`application/problem+json`):

```json
{
  "type": "urn:problem-type:f1ow:validation",
  "title": "One or more arguments are invalid",
  "status": 400,
  "detail": "See 'errors' for each invalid argument.",
  "instance": "/v1/market/candles/BTC",
  "errors": { "interval": ["must be one of: 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d, 1w"] }
}
```

| Status | Meaning |
| --- | --- |
| `400` | An argument is missing or invalid; `errors` names each one. |
| `401` / `403` | Missing or rejected credential. |
| `402` | x402 payment required, or the account's period or balance is used up. |
| `502` | A data source could not answer. Not charged; retry later. |
| `500` | Unexpected server error. Not charged. |

## Specs

- [OpenAPI 3.1](https://mcp.f1ow.com/openapi.json): import it into Postman, Insomnia or a code generator. It includes an example request for every operation.
- [API catalog (RFC 9727)](https://mcp.f1ow.com/.well-known/api-catalog)

> Get an API key: https://www.f1ow.com/dashboard