agno-optimistfi

OptimistFi data as tools for Agno agents: perpetual futures across venues, prop firms that fund crypto and stock perps traders, and US company disclosures from SEC EDGAR and the US House Clerk.

The tools call OptimistFi's public endpoint, https://mcp.optimistfi.com/mcp. No API key is needed.

Install

pip install agno-optimistfi

It needs Python 3.9 or later and Agno 2.3.23 or later.

Quick start

from agno.agent import Agent
from agno.models.openai import OpenAIChat

from agno_optimistfi import OptimistFiTools

agent = Agent(
    model=OpenAIChat(id="gpt-5-mini"),
    tools=[OptimistFiTools()],
    instructions=["Name the source and the date of each figure you quote."],
    markdown=True,
)

agent.print_response("Which House members traded NVDA this year, and have its insiders been selling?")

Any model Agno supports can drive the tools. A runnable version is in examples/research_agent.py.

Tools

Every tool has an async twin (aget_perp, aget_insider_trades and so on), which Agno uses when the agent runs with arun.

Choosing tools

All eight are registered by default. Turn any off to keep a small model's tool list short:

# US company disclosures only
OptimistFiTools(
    enable_get_perp=False,
    enable_get_perp_history=False,
    enable_get_perps_market=False,
    enable_get_prop_firms=False,
)

timeout (seconds, default 60) and base_url are also settable.

What a tool returns

Each tool returns JSON. Records share one shape:

{
  "entity": {"ticker": "NVDA", "name": "NVIDIA CORP", "cik": "0001045810"},
  "type": "gov_trade",
  "event_time": "2026-10-01",
  "as_of": "2026-10-22",
  "confidence": "confirmed",
  "source": {"name": "US House Clerk PTR", "url": "https://disclosures-clerk.house.gov/...", "license": "public"},
  "data": {"politician": "Cleo Fields", "txn_type": "buy", "amount_low": 1001, "amount_high": 15000, "account": "Morgan Stanley - E*TRADE IRA"}
}

• event_time is when the event happened or is expected.
• as_of is when it became public.
• confidence is confirmed for a filed fact and estimated for a projected date, such as a next earnings date, which also carries its basis.
• source.url links to the filing or page the record was read from.

A failed request returns {"error": ...} with the reason. When the server is restarting (HTTP 502, 503 or 504), the call is retried once after 5 seconds.

Data and limits

• Sources: SEC EDGAR (Form 4, 8-K), the US House Clerk (periodic transaction reports), ClinicalTrials.gov, the prop firms' own pages, and exchange data across perps venues.
• Coverage: the House only for congressional trades; US-listed companies for SEC data.
• Not advice: the data is for research. It is not investment advice, and nothing here places an order.

Development

pip install -e ".[test]"
pytest

The tests mock the endpoint, so they run offline.

License

MIT. See LICENSE.