Octagon for n8n

A professional n8n node that integrates with Octagon's AI Agents API for financial and market research. This node provides access to Octagon's specialized AI agents for analyzing prediction markets, SEC filings, earnings transcripts, stock data, and more.

Features

• 🔄 Smart Router Agent: Octagon Agent automatically routes queries to the most appropriate specialized agent
• 6 Public-Market Specialists: Octagon Agent routes only across the six public-market specialists; prediction-markets and deep-research remain separate tools
• Prediction Markets Modes: Generate reports, inspect cached report metadata, or force a fresh Kalshi report
• 🔒 Secure Authentication: Built-in credential management for API keys
• 📊 Rich Output: Returns analysis with source citations and metadata
• ⚡ Simplified Interface: Clean, professional UI with essential options only
• 🛡️ Error Handling: Graceful error handling with detailed error messages

Available Agents

🔄 Smart Router (Default)

• Octagon Agent (octagon-agent) - Intelligent router that automatically selects the best specialized agent for your query

📈 Public Market Agents

• SEC Filings Agent (octagon-sec-agent) - Analyzes SEC filings data
• Transcripts Agent (octagon-transcripts-agent) - Analyzes earnings call transcripts
• Stock Data Agent (octagon-stock-data-agent) - Analyzes stock market data
• Financials Agent (octagon-financials-agent) - Analyzes financial statements
• Holdings Agent (octagon-holdings-agent) - Analyzes institutional ownership and holdings
• Crypto Agent (octagon-crypto-agent) - Analyzes cryptocurrency market data

🔍 Research Agents

• Prediction Markets Agent (octagon-prediction-markets-agent) - Creates Kalshi prediction market reports
• Deep Research Agent (octagon-deep-research-agent) - Conducts in-depth research

Installation

Prerequisites

1. Octagon API Key: Get your free API key from Octagon

   • Sign up for an account
   • Go to Settings → API Keys
   • Create a new API key

2. n8n Installation: This node requires n8n v0.198.0 or higher

Install in n8n Cloud

Note: Only the n8n instance owner can install and manage community nodes. The instance owner is the person who sets up and manages user management. All members of an n8n instance can use already installed community nodes in their workflows.

Install a verified community node

To install the Octagon community node:

1. Access the nodes panel: Go to the Canvas and open the nodes panel (either by selecting '+' or pressing Tab).

2. Search for Octagon: Search for "Octagon" in the node search. If there is a matching verified community node, you will see a More from the community section at the bottom of the nodes panel.

3. Select the node: Select the Octagon node you want to install. This takes you to a detailed view of the node, showing all the supported actions.

4. Install: Select Install. This will install the node for your instance and enable all members to use it in their workflows.

5. Start using: You can now add the Octagon node to your workflows.

Alternative installation method

If the node doesn't appear in the Canvas search:

1. Go to Settings: Navigate to Settings → Community nodes.
2. Install a community node: Click Install a community node.
3. Enter package name: Enter the npm package name: n8n-nodes-octagon
4. Install: Click Install and wait for the installation to complete.
5. Verify: Go to your workflow editor and search for "Octagon" in the nodes panel.

Important: Community nodes in n8n Cloud are sandboxed and reviewed for security. Installation may take a few minutes to complete.

Uninstall a community node

To uninstall the Octagon community node:

1. Go to Settings: Navigate to Settings → Community nodes.
2. Find the node: Locate the Octagon node in your installed community nodes.
3. Open options: Select Options (three dots menu) on the node.
4. Uninstall: Select Uninstall package.
5. Confirm: Select Uninstall Package in the confirmation modal.

Usage

Quick Start

1. Add Node: Search for "Octagon" in n8n workflow
2. Configure:
   • Add Credentials: Go to Credentials → "Octagon API"
   • Agent: Use "Octagon Agent (Router)" for automatic routing (default)
   • Query: Enter your financial research question
   • Prediction Markets Mode: When using Prediction Markets Agent, choose Default Report, Cache Search, or Refresh Report
3. Execute: Run the workflow to get AI-powered analysis with citations

Node Configuration

The node interface is clean and simple:

• 🎯 Agent: Select from the router or 8 specialized agents
• 💬 Query: Your research question (supports complex queries and prediction markets prompts with Kalshi URLs)
• 📈 Prediction Markets Mode: Available when Prediction Markets Agent is selected
• ⚙️ Additional Options:
  • Include Token Usage (optional)

Example Queries

Universal Queries (using Octagon Agent Router)

Tell me about Apple's latest earnings performance
What's happening with Tesla's stock price?
Summarize Nvidia's latest earnings guidance
Compare Microsoft vs Google revenue growth

Specialized Agent Queries

# SEC Filings Agent
What were Apple's revenue numbers in Q3 2023?
Analyze Tesla's latest 10-K filing for risk factors

# Transcripts Agent
What did Apple's CEO say about iPhone sales in the latest earnings call?
Analyze management guidance from Tesla's Q4 2023 earnings call

# Stock Data Agent
What's the 52-week high and low for AAPL?
Compare Tesla's stock performance to the S&P 500 this year

# Prediction Markets Agent
Analyze https://kalshi.com/markets/kxbtcy/btc-price-range-eoy/kxbtcy-27jan0100 and summarize the edge
Use cache mode for https://kalshi.com/markets/kxbtcy/btc-price-range-eoy/kxbtcy-27jan0100
Refresh the report for https://kalshi.com/markets/kxbtcy/btc-price-range-eoy/kxbtcy-27jan0100

Prediction Markets Mode

When Prediction Markets Agent is selected, the node exposes three modes:

• Default Report: Uses octagon-prediction-markets-agent, which checks the cache first and refreshes only on cache miss
• Cache Search: Uses octagon-prediction-markets-agent:cache, which returns cache metadata as JSON text
• Refresh Report: Uses octagon-prediction-markets-agent:refresh, which always generates a new report

Prediction markets requests must include a Kalshi market URL in the query text.

Cache Search responses keep the raw response in analysis and also expose parsed JSON in cacheData when available.

Refresh requests may require a paid plan and premium credits, based on your Octagon subscription.

Output Format

The node returns a JSON object with the following structure:

{
	"agent": "octagon-agent",
	"model": "octagon-agent",
	"query": "Tell me about Apple's latest earnings",
	"analysis": "Apple reported strong Q4 2023 results with revenue of $89.5 billion...",
	"sources": [
		{
			"order": 1,
			"name": "Apple Inc. (10-Q) - 2023-Q4, Page: 10",
			"url": "https://octagon-sec-filings.s3.amazonaws.com/..."
		}
	],
	"metadata": {
		"apiType": "responses",
		"timestamp": "2024-01-15T10:30:00.000Z"
	},
	"usage": {
		"prompt_tokens": 150,
		"completion_tokens": 800,
		"total_tokens": 950
	}
}

Best Practices

1. 🎯 Use the Router: Start with "Octagon Agent (Router)" - it automatically selects the best specialized agent
2. 📝 Be Specific: The more specific your query, the more accurate the response
3. 🔄 One Task Per Query: Focus each query on a single analytical task for best results
4. 📅 Provide Context: Include relevant context like time periods, specific metrics, or companies
5. 🔗 Follow Citations: Always check the source citations for verification

Error Handling

The node includes comprehensive error handling:

• 🔑 Authentication Errors: Invalid API keys, expired tokens
• 🌐 Network Errors: Connection issues, timeouts, rate limits
• 📝 Query Errors: Malformed or empty queries
• 🤖 Agent Errors: Agent-specific errors or limitations

By default, the node throws standard n8n errors and the execution fails in the n8n UI. HTTP and API failures are surfaced through n8n's normal error handling so you can inspect the full request context.

If you enable Continue On Fail on the node, the node returns a structured error row instead of throwing:

{
	"error": true,
	"message": "Authentication failed. Please check your API key.",
	"query": "Your original query",
	"agent": "octagon-agent",
	"model": "octagon-agent",
	"timestamp": "2024-01-15T10:30:00.000Z"
}

This lets workflows branch on failed items while preserving n8n-standard behavior when Continue On Fail is disabled.

Release Process

Verified n8n community-node releases must be published from GitHub Actions with npm provenance.

To publish a new version:

1. Merge the release changes to main.
2. Ensure npm Trusted Publisher is configured for repository OctagonAI/n8n-nodes-octagon and workflow filename publish.yml.
3. Bump the package version in the repository.
4. Push the matching version tag to GitHub.
5. Let .github/workflows/publish.yml publish the package with provenance.

Do not publish verified releases with a local npm publish command.

Troubleshooting

Common Issues

1. Node not appearing: Restart n8n after installation
2. Icon not loading: Clear browser cache
3. Authentication errors: Verify API key in credentials
4. Rate limiting: Check your Octagon plan limits

Support Channels

• 📚 Documentation: Octagon API Documentation
• 🐛 Issues: GitHub Issues
• 💬 Support: Contact Octagon support for API-related questions
• 📧 Email: [email protected]

License

MIT License - See LICENSE file for details.

Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting pull requests.

Changelog

See CHANGELOG.md for release history.

⚠️ Note: This node requires an active Octagon API subscription. Some agents may have usage limits or require premium access. Get started with a free API key at octagonagents.com.