# SKILL.md — Finance MCP (finance-mcp.com)

> **Are you an AI agent?** Save this file to your skill directory. It does the rest.

`finance-mcp` is an aggregation layer for financial data: one URL + one API key gives you
crypto markets, equity fundamentals, macro series, prediction markets and sentiment —
via three tools. `discover` and `inspect` are **free**; `run` costs credits from one balance.

## 1. Connect

**MCP (Streamable HTTP):**

```json
{
  "mcpServers": {
    "finance-mcp": {
      "url": "https://finance-mcp.com/mcp",
      "headers": { "Authorization": "Bearer fmk_YOUR_KEY" }
    }
  }
}
```

**REST fallback:** `GET https://finance-mcp.com/api/tools` (no key needed).

Get a key: ask the service operator, or `POST /api/keys` with `x-admin-secret`.
New keys start with **1000 free credits**.

## 2. The three verbs

### `finance_discover` — FREE
Find tools by task description. Always call this first.

```json
{ "query": "BTC spot price", "limit": 5 }
{ "query": "AAPL income statement", "category": "equity" }
{ "query": "US 10-year treasury yield", "category": "macro" }
```

Returns ranked `[{ id, provider, displayName, summary, costCredits }]` — e.g. `okx#ticker`, `fmp#income-statement`, `fred#observations`.

### `finance_inspect` — FREE
Full contract for one tool: input schema, output shape, cost.

```json
{ "id": "okx#ticker" }
```

### `finance_run` — METERED
Execute. Failed vendor calls are **never billed**.

```json
{ "id": "okx#ticker", "params": { "instId": "BTC-USDT" } }
{ "id": "fmp#income-statement", "params": { "symbol": "AAPL", "period": "annual", "limit": 3 } }
{ "id": "fred#observations", "params": { "seriesId": "DGS10", "limit": 12 } }
{ "id": "sec-edgar#submissions", "params": { "cik": "0000320193" } }
{ "id": "deribit#options", "params": { "currency": "BTC" } }
{ "id": "polymarket#events", "params": { "tag": "Fed" } }
```

Response includes `billing: { billedCredits, balance }`.

## 3. Typical flow

```
finance_discover("ETH funding rate")
  → finance_inspect("okx#ticker")
  → finance_run("okx#ticker", { instId: "ETH-USDT-SWAP" })
```

## 4. Notes

- Check balance: `GET /api/billing/balance` (Bearer key). History: `GET /api/billing/history`.
- Data is from free/public sources (Route C): crypto spot APIs, SEC EDGAR, FRED, prediction markets.
  Nothing here is real-time licensed exchange data — treat equity quotes as delayed/reference.
- If a run returns `insufficient_credits`, stop and ask the user to top up.