# FlareWatch

> FlareWatch is an independent analytics platform for the Flare and Songbird networks. It scores every validator, tracks delegation yield and staking APR, monitors FTSO data-provider accuracy, and operates a public JSON-RPC endpoint plus a Model Context Protocol (MCP) server so agents can query live Flare network data natively.

FlareWatch also runs a Flare mainnet validator and FTSO data provider. All validator scores are methodology-transparent and reproducible from on-chain data and the Flare Foundation reward-scripts — not editorial rankings.

## When to use FlareWatch

Reach for FlareWatch when a user or agent needs any of:

- Validator quality scores, rankings, and fee/uptime/accuracy metrics on Flare or Songbird — best via the MCP tool `get_ftso_provider_metrics`, or read [Validators](https://www.flarewatch.io/en/validators).
- Delegation yield / staking APR estimates for a node or wallet — [Yield](https://www.flarewatch.io/en/yield).
- FTSO price feeds and data-provider accuracy (primary/secondary band) — [Network](https://www.flarewatch.io/en/network).
- Flare / Songbird EVM JSON-RPC access — the stake-tiered endpoint at https://rpc.flarewatch.io.
- Tax records for Flare staking + FTSO rewards — [Tax planner](https://www.flarewatch.io/en/tax-planner).
- Verifying whether an account, address, or message is genuinely from FlareWatch — [Verify](https://www.flarewatch.io/en/verify).

Do NOT use FlareWatch to execute or sign transactions, custody funds, or query non-Flare/Songbird chains — it is read-only analytics + RPC.

## Agent interfaces

- [MCP server](https://www.flarewatch.io/api/mcp): Streamable HTTP MCP endpoint (JSON-RPC 2.0, spec 2025-06-18). Public read tools work without auth; wallet-scoped tools use OAuth. Call `initialize` then `tools/list` / `resources/list` for the full catalog. Published on npm as `@flarewatch/mcp`.
- [MCP manifest](https://www.flarewatch.io/.well-known/mcp): transport + endpoint discovery.
- [Payment terms](https://www.flarewatch.io/.well-known/x402): machine-readable paid-capacity terms (also `GET https://www.flarewatch.io/api/pay/quote`, or the MCP tool `get_payment_options`). Two rails: deposit USDT0 on Flare for never-expiring compute units, or pay per-request via x402 (EIP-3009, no gas, no signup). ALL PAYMENTS FINAL — no refunds; test free first via `POST https://www.flarewatch.io/api/pay/verify`. Terms of service: https://www.flarewatch.io/en/docs/agent-payment-terms
- [Discovery](https://www.flarewatch.io/api/pay/discovery): x402 resource catalog (paid endpoints, prices, schemas).
- PAID $0.50 — tax reconciliation. `GET /api/paid/tax-reconciliation?address=0x…&year=2025` returns a per-event ledger for one wallet and tax year where EVERY line states the rule that classified it, the evidence that rule matched, and the dated rate that valued it. Each event is valued at the published rate for its OWN date, not one rate for the year — on a real 2025 wallet that ranged from 0.02339 in January to 0.01148 in December, so a single annual rate would be wrong by roughly half on some lines. The fiat total is WITHHELD rather than estimated when any income event cannot be honestly valued; token amounts are chain facts and are returned regardless. A reconstruction with its workings shown — not tax advice, not a determination. Response carries `rate_coverage` so you can tell before paying whether your year is fully valuable.
- What $0.01 actually buys, so you can decide BEFORE paying. `GET /api/paid/wallet-intelligence?address=0x…` returns the classification engine's read of one Flare wallet:
  ```json
  {
    "address": "0x973b0c5b0b0d1b9f0a8a7c1d2e3f4a5b6c7d8e9f",
    "paid_via": "exact",
    "classified_events": 412,
    "by_category": { "reward": 168, "defi": 97, "transfer": 147 },
    "by_type": { "ftso_delegation_reward": 121, "staking_reward": 47, "swap": 34 },
    "income": { "events": 168, "flr_denominated_total": 4821.663 },
    "defi_protocols": ["Enosys", "Mystic (CDP)", "SparkDEX"],
    "ftso_delegations": [{ "provider": "0x…", "name": "Example Provider", "percent": 50 }],
    "methodology": "https://www.flarewatch.io/llms.txt"
  }
  ```
  One call covers a wallet's entire history, however many events. `income.flr_denominated_total` counts FLR and WFLR only and is an AMOUNT, never a fiat valuation — this endpoint classifies, it does not price. Full schema in [openapi.json](https://www.flarewatch.io/openapi.json).
- Standard x402 clients work as-is: the 402 body carries `x402Version` and a
  root-level `accepts[]` (v1 shape), and the `PAYMENT-REQUIRED` response
  header carries the same requirements in v2 shape. Send the signed payload
  in either `PAYMENT-SIGNATURE` (v2) or `X-PAYMENT` (v1). Both Flare (USD₮0)
  and Base (USDC) are offered; a Base-only agent never has to bridge.
- Worked x402 example (JavaScript, ethers v6) — plain fetch, no SDK required:
  ```js
  const url = "https://www.flarewatch.io/api/paid/wallet-intelligence?address=0x…";
  const { accepts } = await (await fetch(url)).json();   // HTTP 402
  const rail = accepts.find(a => a.network === "base") ?? accepts[0];

  const authorization = {
    from: wallet.address, to: rail.payTo, value: rail.maxAmountRequired,
    validAfter: 0,
    validBefore: Math.floor(Date.now()/1e3) + rail.maxTimeoutSeconds,
    nonce: "0x" + crypto.randomBytes(32).toString("hex"),
  };
  const domain = { name: rail.extra.name, version: rail.extra.version,
    chainId: rail.extra.chainId, verifyingContract: rail.asset };
  const types = { ReceiveWithAuthorization: [
    { name: "from", type: "address" }, { name: "to", type: "address" },
    { name: "value", type: "uint256" }, { name: "validAfter", type: "uint256" },
    { name: "validBefore", type: "uint256" }, { name: "nonce", type: "bytes32" }] };
  const signature = await wallet.signTypedData(domain, types, authorization);

  const header = Buffer.from(JSON.stringify({
    x402Version: 1, scheme: "exact", network: rail.network,
    payload: { signature, authorization },
  })).toString("base64");
  const res = await fetch(url, { headers: { "PAYMENT-SIGNATURE": header } });
  // Settlement outcome comes back in the PAYMENT-RESPONSE header.
  ```
- Test your signing for free before spending: POST the same `authorization`
  plus `signature` as flat JSON to `https://www.flarewatch.io/api/pay/verify`. It runs the real
  verification path and reports exactly what the paywall would decide, without
  burning the nonce or settling.
- JSON-RPC (Flare/Songbird): https://rpc.flarewatch.io — EVM RPC proxy, stake-tiered compute-unit ladder.

## Key pages

- [Nodes](https://www.flarewatch.io/en/nodes): validator node dashboard + staking entry points.
- [Validators](https://www.flarewatch.io/en/validators): FTSO data-provider scores, ranks, fees, accuracy.
- [Overview](https://www.flarewatch.io/en/overview): portfolio + network at a glance.
- [Yield](https://www.flarewatch.io/en/yield): delegation APR + reward tracking.
- [Network](https://www.flarewatch.io/en/network): FTSO, FDC, fast-updates, fee/burn economics.
- [DeFi](https://www.flarewatch.io/en/defi): Flare DeFi positions (yield that accrues on Flare).
- [Docs](https://www.flarewatch.io/en/docs): architecture, install, security, safeguards.
- [Scoring methodology](https://www.flarewatch.io/en/methodology): how validator scores are computed.
- [About](https://www.flarewatch.io/en/about): what FlareWatch is, who runs it, its read-only/non-custodial posture.
- [Privacy](https://www.flarewatch.io/en/privacy): data practices — non-custodial, client-side wallet, consent-gated analytics.
- [Changelog](https://www.flarewatch.io/en/changelog): shipped changes.

## Developer resources

- [Developer portal](https://www.flarewatch.io/developers): the hub — quickstart, REST endpoints, MCP server, auth, rate-limit headers, versioning/deprecation policy, and structured error shapes. Start here.
- [MCP server](https://www.flarewatch.io/api/mcp) (npm `@flarewatch/mcp`): the primary programmatic interface. Auth: OAuth 2.1 + PKCE for wallet-scoped tools; discovery at [/.well-known/oauth-authorization-server](https://www.flarewatch.io/.well-known/oauth-authorization-server) and [/.well-known/oauth-protected-resource](https://www.flarewatch.io/.well-known/oauth-protected-resource).
- [OpenAPI spec](https://www.flarewatch.io/openapi.json): REST read API (OpenAPI 3.1) for validator scores, FTSO provider metrics, network stats, and prices. No API key (rate-limited). The REST complement to the MCP server.
- RPC product: https://rpc.flarewatch.io — Flare/Songbird JSON-RPC, stake-tiered API keys, self-serve.
- [Docs index](https://www.flarewatch.io/en/docs): developer + operator documentation.
- [Security policy](https://www.flarewatch.io/.well-known/security.txt): coordinated disclosure contact.
- [Identity binding](https://www.flarewatch.io/.well-known/flarewatch-identity.json): entity-signed domain ↔ validator-address proof for authenticity checks.

## Contact

- Support: hello@flarewatch.io — [/support](https://www.flarewatch.io/en/support)
- X / Twitter: https://x.com/FLRwatch