# Build on Flicker

The same signals, analysis and market data the apps run on, available as an OpenAPI-described REST API and as an MCP server your AI agent can call directly.

## When to use Flicker

Reach for Flicker when a question needs a computed market read rather than a headline.

- You need a buy / hold / sell read on one asset, with the zones, stop loss and target behind it — not just a price.
- You need to screen thousands of assets for a setup at once — breakouts, oversold zones, volume surges — instead of asking ticker by ticker.
- You need sentiment as a number per asset, not one index for the whole market: a Fear & Greed score from 0 to 100 for a specific coin, stock or currency.
- You need live crypto, stock and forex prices, perpetual funding rates, or market breadth in a single call.
- You need a user's own exchange positions, balances and orders, aggregated across exchanges and read-only.

Do not reach for Flicker to place an order, move funds, or hold custody. The product is read-only by construction and has no execution path — pair it with an exchange API for that.

## The REST API

One HTTPS host serves every endpoint. The full surface is described by a machine-readable OpenAPI 3.1 document — every operation has a unique operation id, typed parameters and a typed response schema, so it drops straight into a client generator or an LLM function-calling loop.

- Base URL: `https://api.flicker.finance`
- OpenAPI 3.1 document: https://api.flicker.finance/docs/openapi.json
- Interactive reference: https://api.flicker.finance/docs

## Authentication

Create a key yourself in the API Keys tab of your account — no sales call, no waiting list — and send it as a request header. A key reaches the read-only market-data surface only: analysis, assets, insights, config and exchanges. It cannot read another account, place a trade or move funds. There is no anonymous tier; a request with no valid credential is refused.

- Header: `x-api-key: <your key>`
- Key scope: `/v2/analysis`, `/v2/assets`, `/v2/insights`, `/v2/config`, `/v1/exchanges`
- Self-serve key management: https://flicker.finance/account (API Keys tab)
- Daily credit balance: `GET https://api.flicker.finance/v1/users/api_keys/credits`

## Quickstart

Three calls that answer with real data the moment your key exists.

```bash
curl -H "x-api-key: $FLICKER_API_KEY" https://api.flicker.finance/v2/config
curl -H "x-api-key: $FLICKER_API_KEY" https://api.flicker.finance/v2/assets/?limit=5
curl -H "x-api-key: $FLICKER_API_KEY" https://api.flicker.finance/v2/analysis/bitcoin
```

## Rate limits

The budget is weighted per endpoint rather than counted per request, and every response reports where you stand, so a client can throttle itself instead of guessing.

- Budget: 2000 weighted units per 60 seconds, per client IP.
- Headers on every response: `x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-used`, `x-ratelimit-window`; a 429 adds `retry-after`.

## Errors

Every failure answers with the same typed body: a stable machine-readable code, a human-readable message, and a false success flag. Branch on the code — the message is English prose meant for a log, not for a switch statement.

```json
{ "success": false, "code": "NotificationLimitExceeded", "message": "…" }
```

Schema: `ErrorResponse` · documented statuses: 400, 401, 402, 403, 404, 410, 422, 500, 503.

## Versioning and deprecation

The major version lives in the URL path. Both live versions are routed independently, so a breaking change ships under a new path version instead of mutating one you already depend on. API changes are published in the machine-readable release feed, which tags entries by platform.

- Live versions: `/v1/`, `/v2/`
- Release feed: https://flicker.finance/changelog.json

## MCP server

A Model Context Protocol server over Streamable HTTP, so Claude, ChatGPT, Cursor and any other MCP client can call Flicker as tools. Authorization is OAuth 2.1: point your client at the endpoint and it discovers the rest from the challenge.

- Endpoint: `https://api.flicker.finance/mcp`
- Transport: Streamable HTTP · Authorization: OAuth 2.1
- Manifest: https://api.flicker.finance/mcp/manifest.json

---

Canonical HTML: https://flicker.finance/developers
Machine-readable index: https://flicker.finance/llms.txt · API: https://api.flicker.finance/docs/openapi.json · MCP: https://api.flicker.finance/mcp