Fast Setup

Quick Start

Quick Start

Start using FinNotes in minutes

Use this page to reach the first useful outcome quickly: inspect the contract, deploy the Agent Skill, fetch data-series values, or open news details.

View API Documents

Recommended first path

Confirm the contract, mount a key, then run one real data request.

FinNotes is point-based, so the first successful request should prove three things: authentication works, the returned object is useful, and point charging is visible.

API key in server-side environment Permission includes Basic news/report/data Read X-Points-Charged after each request

AI Agent deployment

Install the skill where your agent can read it

Download the Agent Skill, place it in the agent workspace, then mount an API key with the permissions your workflow needs.

01 Choose the target workspace

Use a user-level skill folder for personal workflows, or a project-level folder when the API integration belongs with a specific repository.

Skill install command 
mkdir -p ~/.codex/skills/finnotes-api
unzip finnotes-agent-skill.zip -d ~/.codex/skills/finnotes-api
mkdir -p ~/.openclaw/skills/finnotes-api
unzip finnotes-agent-skill.zip -d ~/.openclaw/skills/finnotes-api
mkdir -p ./.agent/skills/finnotes-api
unzip finnotes-agent-skill.zip -d ./.agent/skills/finnotes-api

Data-series workflow

Discover the series, inspect metadata, then fetch values

This is the normal path for AI agents and applications that need structured economic or market data.

3 requests
1
List available series Find the slug, URL, display name, and unit.

Use this before asking for values. It keeps the first payload light and avoids pulling thousands of data points just to discover what exists.

GET /v1/data-series 
curl "https://platform.finnotes.com/v1/data-series?category=commodities" \
  -H "Authorization: Bearer $FINNOTES_API_KEY"
import os
import requests

response = requests.get(
    "https://platform.finnotes.com/v1/data-series",
    params={"category": "commodities"},
    headers={"Authorization": f"Bearer {os.environ['FINNOTES_API_KEY']}"},
    timeout=20,
)
print(response.json())
Returns: name, slug, url, unit
2
Read one series detail Confirm frequency, source, date coverage, and unit.

Use detail before fetching values when the client needs context for chart labels, date windows, or data reliability checks.

GET /v1/data-series/{slug} 
curl "https://platform.finnotes.com/v1/data-series/gold" \
  -H "Authorization: Bearer $FINNOTES_API_KEY"
import os
import requests

response = requests.get(
    "https://platform.finnotes.com/v1/data-series/gold",
    headers={"Authorization": f"Bearer {os.environ['FINNOTES_API_KEY']}"},
    timeout=20,
)
print(response.json())
Returns metadata only; no historical values.
3
Fetch data points Use all, between, or since.

Use this only after the slug and desired date window are known. Pricing is based on returned data-point count.

GET /v1/data-series/{slug}/points 
curl "https://platform.finnotes.com/v1/data-series/gold/points?range=since&start_date=2024-01-01" \
  -H "Authorization: Bearer $FINNOTES_API_KEY"
import os
import requests

response = requests.get(
    "https://platform.finnotes.com/v1/data-series/gold/points",
    params={"range": "since", "start_date": "2024-01-01"},
    headers={"Authorization": f"Bearer {os.environ['FINNOTES_API_KEY']}"},
    timeout=20,
)
print(response.json())
Charge: 250 returned points / 1 point, minimum 1 point.

News workflow

List available articles, then open the detail you need

The list endpoint returns routing metadata only. Use the returned type and slug to request detail content.

common flow
1
List news metadata Scan titles, deks, URLs, types, and slugs.

Start here for daily monitoring. The response is lightweight enough for agent triage and user-facing article selection.

GET /v1/news 
curl "https://platform.finnotes.com/v1/news?range=today&type=all" \
  -H "Authorization: Bearer $FINNOTES_API_KEY"
import os
import requests

response = requests.get(
    "https://platform.finnotes.com/v1/news",
    params={"range": "today", "type": "all"},
    headers={"Authorization": f"Bearer {os.environ['FINNOTES_API_KEY']}"},
    timeout=20,
)
print(response.json())
Returns metadata only: title, url, dek, type, slug.
2
Open market-news detail Use when a list item has type: market-news.

Market-news detail is the normal path for time-sensitive article content after the list endpoint has identified the target item.

GET /v1/news/market-news/{slug} 
curl "https://platform.finnotes.com/v1/news/market-news/oil-risk-premium-cools" \
  -H "Authorization: Bearer $FINNOTES_API_KEY"
import os
import requests

response = requests.get(
    "https://platform.finnotes.com/v1/news/market-news/oil-risk-premium-cools",
    headers={"Authorization": f"Bearer {os.environ['FINNOTES_API_KEY']}"},
    timeout=20,
)
print(response.json())
Charge: 1 point.
3
Open chart-news detail Use when a list item has type: chart-news.

Chart-news detail is priced separately because it contains chart-specific narrative and associated visual context.

GET /v1/news/chart-news/{slug} 
curl "https://platform.finnotes.com/v1/news/chart-news/us-yields-breakout" \
  -H "Authorization: Bearer $FINNOTES_API_KEY"
import os
import requests

response = requests.get(
    "https://platform.finnotes.com/v1/news/chart-news/us-yields-breakout",
    headers={"Authorization": f"Bearer {os.environ['FINNOTES_API_KEY']}"},
    timeout=20,
)
print(response.json())
Charge: 1.25 points.