### Development Environment Setup

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/README.md

This code block outlines the steps for setting up the development environment for the project. It includes installing dependencies using Bun, configuring environment variables by copying an example file, starting the development server with hot-reloading, and building for production.

```bash
bun install
cp .env.example .env  # configure API keys
bun run dev           # hot-reload
bun run build         # production build
```

--------------------------------

### MCP Server Installation and Usage

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Instructions for installing and starting the MCP server, which allows AI agents to discover and use gateway tools. It details the command to run the server and lists example tools that can be called.

```bash
cd mcp-server
npm install
npm run build
npm start
```

--------------------------------

### MCP Server Setup and Start

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/README.md

Instructions for setting up and running the auto-generated MCP (Model Context Protocol) server. This server facilitates AI agent tool discovery. It involves navigating to the `mcp-server` directory, installing dependencies, building the project, and starting the server with stdio transport.

```bash
cd mcp-server
npm install && npm run build
npm start  # stdio transport
```

--------------------------------

### Install and Configure cloudflared for Tunnel

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/DEPLOYMENT.md

Installs the cloudflared daemon, authenticates with Cloudflare, creates a tunnel, configures ingress rules, routes DNS, and sets up the tunnel to run as a systemd service. This is the recommended method for zero-cost deployment.

```bash
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared

cloudflared tunnel login

cloudflared tunnel create financial-oracles

# Configuration file (~/.cloudflared/config.yml):
tunnel: <TUNNEL_ID>
credentials-file: /root/.cloudflared/<TUNNEL_ID>.json

ingress:
  - hostname: oracles.yourdomain.com
    service: http://localhost:3000
  - service: http_status:404

cloudflared tunnel route dns financial-oracles oracles.yourdomain.com

cloudflared service install
systemctl start cloudflared
systemctl enable cloudflared
```

```bash
#!/bin/bash
# Run after cloudflared login

DOMAIN="oracles.yourdomain.com"  # Change this

# Create tunnel
TUNNEL_ID=$(cloudflared tunnel create financial-oracles 2>&1 | grep -oP 'Created tunnel.*with id \K[a-f0-9-]+')

# Create config
mkdir -p ~/.cloudflared
cat > ~/.cloudflared/config.yml << EOF
tunnel: $TUNNEL_ID
credentials-file: /root/.cloudflared/$TUNNEL_ID.json

ingress:
  - hostname: $DOMAIN
    service: http://localhost:3000
  - service: http_status:404
EOF

# Route DNS (if using Cloudflare DNS)
cloudflared tunnel route dns financial-oracles $DOMAIN

# Install as service
cloudflared service install
systemctl enable cloudflared
systemctl start cloudflared

echo "Tunnel active at https://$DOMAIN"
```

--------------------------------

### MCP Server Integration

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Instructions for installing and starting the MCP server, which enables AI agents to discover and use gateway tools via the Model Context Protocol. Includes an example Claude Desktop MCP configuration.

```APIDOC
## MCP Server Integration

### Description
The included MCP server enables AI agents to discover and use all gateway tools via the Model Context Protocol.

### Installation and Startup

```bash
# Install and start MCP server
cd mcp-server
npm install
npm run build
npm start
```

### AI Agent Tool Calls

```bash
# The server exposes tools via stdio transport
# AI agents can call tools like:
# - getHealth
# - getDemoQuote
# - getStockQuote (requires X-Payment parameter)
# - getCryptoPrices
# - screenSanctionsAddress
# - bundleSecSnapshot
```

### Claude Desktop MCP Configuration

```json
// claude_desktop_config.json
{
  "mcpServers": {
    "financial-oracles": {
      "command": "node",
      "args": ["/path/to/mcp-server/build/index.js"],
      "env": {}
    }
  }
}
```
```

--------------------------------

### Install and Configure Caddy Reverse Proxy

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/DEPLOYMENT.md

Installs the Caddy web server and configures it to act as a reverse proxy for localhost:3000, including optional rate limiting for specific API paths. This is suitable if you already have a VPS exposed.

```bash
apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
apt update && apt install caddy

# Configuration file (/etc/caddy/Caddyfile):
oracles.yourdomain.com {
    reverse_proxy localhost:3000
    
    # Rate limiting (optional)
    @ratelimited {
        path /sanctions/* /sec/* /perp/*
    }
    rate_limit @ratelimited {
        zone api_limit {
            key {remote_host}
            events 100
            window 1m
        }
    }
}

systemctl enable caddy
systemctl start caddy
```

--------------------------------

### Quick Start: Test Free Demo Endpoint

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/README.md

This snippet demonstrates how to access a free demo endpoint to test the gateway's functionality without requiring any payment. It uses `curl` to make a GET request to the `/demo/quote` endpoint.

```bash
# Free demo endpoint - no payment needed
curl https://agents.krumpybot.com/demo/quote
```

--------------------------------

### Quick Start: Pay and Get Data

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/README.md

This snippet illustrates how to make a paid request to an endpoint after completing a payment via x402. The transaction hash (`tx_hash`) of the payment, made with USDC on Base, is included in the `X-Payment` header.

```bash
# After paying via x402 (USDC on Base), include tx hash
curl -H "X-Payment: 0x<tx_hash>" https://agents.krumpybot.com/stocks/quote/AAPL
```

--------------------------------

### Configure Fly.io Deployment with Dockerfile

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/DEPLOYMENT.md

Sets up a `fly.toml` configuration file for deploying an application on Fly.io, specifying build settings, HTTP service configuration, and VM resources. It also includes a Dockerfile for building the application image, installing dependencies, and exposing the necessary port.

```toml
app = "financial-oracles"
primary_region = "fra"

[build]
  dockerfile = "Dockerfile"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 0

[[vm]]
  cpu_kind = "shared"
  cpus = 1
  memory_mb = 512
```

```dockerfile
FROM oven/bun:1 as base

# Install Python
RUN apt-get update && apt-get install -y python3 python3-pip python3-venv

WORKDIR /app
COPY . .

# Install dependencies
RUN bun install
RUN cd skills/sanctions-oracle && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

EXPOSE 3000
CMD ["bun", "run", "src/index.ts"]
```

--------------------------------

### Quick Start: Check Pricing Information

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/README.md

This example shows how to retrieve pricing information for endpoints. By making a request to a specific endpoint without the `X-Payment` header, the API returns a 402 status code along with a JSON object detailing the payment requirements, including `maxAmountRequired`.

```bash
# Any endpoint without X-Payment returns 402 with pricing
curl https://agents.krumpybot.com/stocks/quote/AAPL
# Returns: { x402Version: 1, accepts: [{ maxAmountRequired: "5000", ... }] }
```

--------------------------------

### GET /perp/arbitrage

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Scans for funding rate arbitrage opportunities across decentralized perpetual exchanges.

```APIDOC
## GET /perp/arbitrage

### Description
Scans for funding rate arbitrage opportunities across decentralized perpetual exchanges.

### Method
GET

### Endpoint
https://agents.krumpybot.com/perp/arbitrage

### Parameters
#### Query Parameters
- **min_spread** (number) - Optional - The minimum spread to filter opportunities.

#### Request Body
None

### Request Example
```bash
curl -H "X-Payment: 0xabc123...txhash" "https://agents.krumpybot.com/perp/arbitrage?min_spread=0.01"
```

### Response
#### Success Response (200)
- **opportunities** (array) - A list of identified arbitrage opportunities.
  - **symbol** (string) - The trading symbol.
  - **long_exchange** (string) - The exchange to go long on.
  - **long_rate** (number) - The funding rate for the long position.
  - **short_exchange** (string) - The exchange to go short on.
  - **short_rate** (number) - The funding rate for the short position.
  - **spread** (number) - The difference between short and long rates.
  - **annualized_return** (number) - The potential annualized return.
  - **recommendation** (string) - Recommended action (e.g., Long X, Short Y).
- **min_spread_filter** (number) - The minimum spread filter applied.
- **timestamp** (string) - The timestamp when the scan was performed.

#### Response Example
```json
{
  "opportunities": [
    {
      "symbol": "SOL-PERP",
      "long_exchange": "gmx",
      "long_rate": -0.0005,
      "short_exchange": "hyperliquid",
      "short_rate": 0.0025,
      "spread": 0.003,
      "annualized_return": 109.5,
      "recommendation": "Long GMX, Short Hyperliquid"
    }
  ],
  "min_spread_filter": 0.01,
  "timestamp": "2024-01-15T20:00:00.000Z"
}
```
```

--------------------------------

### Get Pricing Information for All Endpoints (Bash)

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Retrieves pricing information for all 69 endpoints of the Financial Oracles Gateway. Prices are listed in USDC and indicate the cost for accessing specific data or operations.

```bash
# Get all endpoint prices
curl https://agents.krumpybot.com/pricing

# Response:
{
  "currency": "USDC",
  "network": "base",
  "receiver": "0x71A2CED2074F418f4e68a0A196FF3C1e59Beb32E",
  "endpoints": {
    "sec/company": 0.005,
    "sec/financials": 0.02,
    "stocks/quote": 0.005,
    "crypto/prices": 0.002,
    "forex/rates": 0.002,
    "sanctions/address": 0.01,
    "bundle/market_snapshot": 0.02
  },
  "payment_header": "X-Payment: <tx_hash>"
}
```

--------------------------------

### Claude Desktop MCP Configuration

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Example configuration for Claude Desktop to connect to the MCP server for the financial-oracles service. This JSON file specifies the command and arguments needed to launch the server.

```json
{
  "mcpServers": {
    "financial-oracles": {
      "command": "node",
      "args": ["/path/to/mcp-server/build/index.js"],
      "env": {}
    }
  }
}
```

--------------------------------

### GET /perp/funding

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Returns cross-exchange funding rates for perpetual futures markets on decentralized exchanges.

```APIDOC
## GET /perp/funding

### Description
Returns cross-exchange funding rates for perpetual futures markets on decentralized exchanges.

### Method
GET

### Endpoint
https://agents.krumpybot.com/perp/funding

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -H "X-Payment: 0xabc123...txhash" https://agents.krumpybot.com/perp/funding
```

### Response
#### Success Response (200)
- **funding_rates** (array) - A list of funding rates for different symbols.
  - **symbol** (string) - The trading symbol (e.g., BTC-PERP).
  - **exchanges** (object) - Funding rates per exchange.
  - **average** (number) - The average funding rate across exchanges.
  - **annualized** (number) - The annualized funding rate.
- **timestamp** (string) - The timestamp when the data was retrieved.

#### Response Example
```json
{
  "funding_rates": [
    {
      "symbol": "BTC-PERP",
      "exchanges": {
        "hyperliquid": 0.0012,
        "gmx": 0.0008,
        "dydx": 0.0015
      },
      "average": 0.00117,
      "annualized": 42.8
    },
    {
      "symbol": "ETH-PERP",
      "exchanges": {
        "hyperliquid": 0.0008,
        "gmx": 0.0006,
        "dydx": 0.0010
      },
      "average": 0.0008,
      "annualized": 29.2
    }
  ],
  "timestamp": "2024-01-15T20:00:00.000Z"
}
```
```

--------------------------------

### Get Forex Exchange Rates (Bash)

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Retrieves current exchange rates for over 200 currencies against a specified base currency. Requires a payment header.

```bash
# Get USD exchange rates
curl -H "X-Payment: 0xabc123...txhash" \
  "https://agents.krumpybot.com/forex/rates?base=USD"
```

--------------------------------

### Get Cryptocurrency Prices (Bash)

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Fetches current prices, 24-hour changes, market caps, and volumes for specified cryptocurrencies. Requires a payment header and a comma-separated list of crypto IDs.

```bash
# Get prices for multiple cryptos
curl -H "X-Payment: 0xabc123...txhash" \
  "https://agents.krumpybot.com/crypto/prices?ids=bitcoin,ethereum,solana"
```

--------------------------------

### Example SEC Snapshot Response

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

A sample JSON response from the SEC snapshot bundle endpoint, containing ticker information, company details, financial data, recent insider trades, and material events.

```json
{
  "ticker": "AAPL",
  "timestamp": "2024-01-15T20:00:00.000Z",
  "company": {
    "cik": "0000320193",
    "name": "Apple Inc.",
    "sic": "3571"
  },
  "financials": {
    "revenues": 383285000000,
    "net_income": 96995000000
  },
  "recentInsiderTrades": [
    { "insider": "Timothy D. Cook", "type": "Sale", "shares": 50000 }
  ],
  "materialEvents": [
    { "form": "8-K", "date": "2024-01-10", "items": ["2.02"] }
  ],
  "bundle": "sec_snapshot",
  "endpointsUsed": ["sec/company", "sec/financials", "sec/insiders", "sec/events"]
}
```

--------------------------------

### Bundle: Market Snapshot Endpoint

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/README.md

Get a market snapshot including quote, analyst ratings, and news for a given symbol. This is a recommended bundle endpoint.

```APIDOC
## GET /bundle/market_snapshot/:symbol

### Description
Retrieves a comprehensive market snapshot for a given symbol, including its quote, analyst ratings, and recent news. Payment is required via x402.

### Method
GET

### Endpoint
`/bundle/market_snapshot/:symbol`

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The stock symbol (e.g., AAPL, GOOG).

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -H "X-Payment: 0x<tx_hash>" https://agents.krumpybot.com/bundle/market_snapshot/AAPL
```

### Response
#### Success Response (200)
- **quote** (object) - The stock quote information.
- **analyst_ratings** (array) - An array of analyst ratings.
- **news** (array) - An array of recent news articles.

#### Response Example
```json
{
  "quote": {
    "symbol": "AAPL",
    "price": 170.50,
    "change": 1.20,
    "change_percent": 0.71
  },
  "analyst_ratings": [
    {
      "source": "Goldman Sachs",
      "rating": "Buy",
      "target_price": 200.00
    }
  ],
  "news": [
    {
      "headline": "Apple announces new M3 chip",
      "source": "TechCrunch",
      "published_at": "2023-10-26T15:30:00Z"
    }
  ]
}
```

#### Error Response (402)
- **x402Version** (string) - The version of the x402 protocol.
- **accepts** (array) - An array detailing the payment options required.

#### Error Response Example (402)
```json
{
  "x402Version": "1",
  "accepts": [
    {
      "maxAmountRequired": "2000",
      "currency": "USDC",
      "network": "Base"
    }
  ]
}
```
```

--------------------------------

### Get Market News Headlines

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Fetches market-wide news headlines, including source, summary, and related stock tickers. Allows filtering by category and limiting the number of results. Requires an 'X-Payment' header.

```bash
# Get market news
curl -H "X-Payment: 0xabc123...txhash" \
  "https://agents.krumpybot.com/news/market?category=general&limit=10"

# Response:
{
  "category": "general",
  "count": 10,
  "news": [
    {
      "headline": "Fed Signals Potential Rate Cuts in 2024",
      "summary": "Federal Reserve officials indicated they may begin cutting interest rates...",
      "source": "Reuters",
      "url": "https://...",
      "datetime": "2024-01-15T18:30:00.000Z",
      "related": "SPY,QQQ,TLT"
    }
  ],
  "timestamp": "2024-01-15T20:00:00.000Z"
}
```

--------------------------------

### Get SEC Financial Metrics (Bash)

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Fetches XBRL financial metrics and computed ratios from SEC filings for a specified ticker. Allows specifying metrics and number of periods. Requires a payment header.

```bash
# Get financial metrics for Apple
curl -H "X-Payment: 0xabc123...txhash" \
  "https://agents.krumpybot.com/sec/financials/AAPL?metrics=Revenues,NetIncomeLoss&periods=4"
```

--------------------------------

### Get Market Snapshot Bundle

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Retrieves a comprehensive market snapshot for a stock symbol in a single API call. This bundle includes stock quote data, analyst estimates, and recent news. Requires an 'X-Payment' header.

```bash
# Get market snapshot bundle
curl -H "X-Payment: 0xabc123...txhash" \
  https://agents.krumpybot.com/bundle/market_snapshot/AAPL

# Response:
{
  "symbol": "AAPL",
  "timestamp": "2024-01-15T20:00:00.000Z",
  "quote": {
    "price": 178.52,
    "change": 1.23,
    "changePercent": 0.69,
    "high": 179.10,
    "low": 176.80,
    "open": 177.25,
    "previousClose": 177.29
  },
  "analystEstimates": [
    { "period": "2024-Q1", "epsEstimate": 2.10, "revenueEstimate": 118000000000 }
  ],
  "recentNews": [
    {
      "headline": "Apple Announces New Product Launch Event",
      "source": "CNBC",
      "datetime": 1705345800,
      "summary": "Apple Inc. has announced a special event...",
      "url": "https://..."
    }
  ],
  "bundle": "market_snapshot",
  "endpointsUsed": ["stocks/quote", "analyst/ratings", "news/company"]
}
```

--------------------------------

### Get Perpetual DEX Funding Rates (Bash)

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Retrieves cross-exchange funding rates for perpetual futures markets on decentralized exchanges. Requires an 'X-Payment' header. Returns a list of funding rates per symbol and exchange.

```bash
# Get funding rates
curl -H "X-Payment: 0xabc123...txhash" \
  https://agents.krumpybot.com/perp/funding

# Response:
{
  "funding_rates": [
    {
      "symbol": "BTC-PERP",
      "exchanges": {
        "hyperliquid": 0.0012,
        "gmx": 0.0008,
        "dydx": 0.0015
      },
      "average": 0.00117,
      "annualized": 42.8
    },
    {
      "symbol": "ETH-PERP",
      "exchanges": {
        "hyperliquid": 0.0008,
        "gmx": 0.0006,
        "dydx": 0.0010
      },
      "average": 0.0008,
      "annualized": 29.2
    }
  ],
  "timestamp": "2024-01-15T20:00:00.000Z"
}
```

--------------------------------

### Bundle: SEC Snapshot Endpoint

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/README.md

Get a snapshot of SEC filings data including company information, financials, insiders, and events for a given ticker. This is a recommended bundle endpoint.

```APIDOC
## GET /bundle/sec_snapshot/:ticker

### Description
Retrieves a consolidated snapshot of SEC filings data for a specified company ticker, including company profile, financial statements, insider transactions, and corporate events. Payment is required via x402.

### Method
GET

### Endpoint
`/bundle/sec_snapshot/:ticker`

### Parameters
#### Path Parameters
- **ticker** (string) - Required - The stock ticker symbol (e.g., AAPL, MSFT).

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -H "X-Payment: 0x<tx_hash>" https://agents.krumpybot.com/bundle/sec_snapshot/AAPL
```

### Response
#### Success Response (200)
- **company_info** (object) - Basic information about the company.
- **financials** (object) - Key financial statement data.
- **insiders** (array) - Recent insider transactions.
- **events** (array) - Upcoming or recent corporate events.

#### Response Example
```json
{
  "company_info": {
    "name": "Apple Inc.",
    "cik": "0000320193",
    "exchange": "NASDAQ"
  },
  "financials": {
    "latest_quarter": "2023-09-30",
    "revenue": 383290000000,
    "net_income": 96990000000
  },
  "insiders": [
    {
      "name": "Tim Cook",
      "transaction": "Sale",
      "shares": -50000,
      "date": "2023-10-20"
    }
  ],
  "events": [
    {
      "type": "Earnings Date",
      "date": "2023-11-02"
    }
  ]
}
```

#### Error Response (402)
- **x402Version** (string) - The version of the x402 protocol.
- **accepts** (array) - An array detailing the payment options required.

#### Error Response Example (402)
```json
{
  "x402Version": "1",
  "accepts": [
    {
      "maxAmountRequired": "4000",
      "currency": "USDC",
      "network": "Base"
    }
  ]
}
```
```

--------------------------------

### Fetch ERC-8004 Agent Card

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Command to get the ERC-8004 agent card, providing details about the Financial Oracles Gateway, its version, identity, x402 compatibility, and entrypoint pricing.

```bash
curl https://agents.krumpybot.com/.well-known/agent.json
```

--------------------------------

### Get SEC Snapshot Bundle

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Retrieves a consolidated SEC data bundle for a given stock symbol, including company profile, financials, insider trades, and material events. This endpoint requires an 'X-Payment' header.

```bash
# Get comprehensive SEC data
curl -H "X-Payment: 0xabc123...txhash" \
  https://agents.krumpybot.com/bundle/sec_snapshot/AAPL
```

--------------------------------

### Get US Treasury Debt Data (Bash)

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Retrieves current US national debt levels, including debt held by the public and intragovernmental debt, along with 30-day trends. Requires an 'X-Payment' header.

```bash
# Get national debt data
curl -H "X-Payment: 0xabc123...txhash" \
  https://agents.krumpybot.com/treasury/debt

# Response:
{
  "total_debt": 34000000000000,
  "debt_held_public": 26500000000000,
  "intragovernmental": 7500000000000,
  "record_date": "2024-01-14",
  "change_30d": 150000000000,
  "trend": [
    { "date": "2024-01-14", "total": 34000000000000 },
    { "date": "2024-01-07", "total": 33925000000000 },
    { "date": "2023-12-31", "total": 33850000000000 }
  ],
  "timestamp": "2024-01-15T20:00:00.000Z"
}
```

--------------------------------

### GET /health

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/DEPLOYMENT.md

Checks the health status of the Financial Oracles Gateway. This endpoint is useful for monitoring the service's availability.

```APIDOC
## GET /health

### Description
Verifies the operational status of the Financial Oracles Gateway.

### Method
GET

### Endpoint
/health

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
```bash
curl https://yourdomain.com/health
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status of the service (e.g., "ok").

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### Verify Gateway Health Check API

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/DEPLOYMENT.md

Checks the health status of the Financial Oracles Gateway by sending a GET request to the /health endpoint. This is a fundamental step to ensure the service is running correctly.

```shell
curl https://yourdomain.com/health
```

--------------------------------

### Get Historical Stock Prices (Bash)

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Retrieves historical OHLCV (Open, High, Low, Close, Volume) candle data for a specified stock symbol. This example shows how to request 30 days of daily candles for AAPL, requiring a payment transaction hash.

```bash
# Get 30 days of daily candles
curl -H "X-Payment: 0xabc123...txhash" \
  "https://agents.krumpybot.com/stocks/historical/AAPL?resolution=D&days=30"
```

--------------------------------

### Fetch x402 Discovery Document

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Command to retrieve the x402 discovery document from the gateway, which lists all available resources for AI agents. The response includes resource URLs, manifest location, and metadata.

```bash
curl https://agents.krumpybot.com/.well-known/x402
```

--------------------------------

### Test Free Demo Stock Quote Endpoint (Bash)

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Tests the free demo endpoint for AAPL stock quotes. This is useful for verifying connectivity and understanding the response format without requiring payment. It returns sample data and information about paid endpoints.

```bash
# Test the free demo endpoint
curl https://agents.krumpybot.com/demo/quote

# Response:
{
  "symbol": "AAPL",
  "price": 178.52,
  "change": 1.23,
  "changePercent": 0.69,
  "high": 179.10,
  "low": 176.80,
  "open": 177.25,
  "previousClose": 177.29,
  "timestamp": "2024-01-15T16:00:00.000Z",
  "demo": true,
  "x402_info": {
    "message": "This is a free demo endpoint. Paid endpoints return richer data.",
    "pricing_url": "https://agents.krumpybot.com/pricing",
    "example_paid": "https://agents.krumpybot.com/stocks/quote/MSFT"
  }
}
```

--------------------------------

### Scan Perp DEX Arbitrage Opportunities (Bash)

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Scans for funding rate arbitrage opportunities across decentralized perpetual exchanges. Requires an 'X-Payment' header and optionally accepts a 'min_spread' query parameter. Returns identified opportunities with spread and return calculations.

```bash
# Find arbitrage opportunities
curl -H "X-Payment: 0xabc123...txhash" \
  "https://agents.krumpybot.com/perp/arbitrage?min_spread=0.01"

# Response:
{
  "opportunities": [
    {
      "symbol": "SOL-PERP",
      "long_exchange": "gmx",
      "long_rate": -0.0005,
      "short_exchange": "hyperliquid",
      "short_rate": 0.0025,
      "spread": 0.003,
      "annualized_return": 109.5,
      "recommendation": "Long GMX, Short Hyperliquid"
    }
  ],
  "min_spread_filter": 0.01,
  "timestamp": "2024-01-15T20:00:00.000Z"
}
```

--------------------------------

### Crypto Prices Endpoint

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/README.md

Get current prices for a list of cryptocurrencies. Payment is required via x402.

```APIDOC
## GET /crypto/prices

### Description
Retrieves the current market prices for a list of popular cryptocurrencies. Payment is required via x402.

### Method
GET

### Endpoint
`/crypto/prices`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **symbols** (string) - Optional - A comma-separated list of cryptocurrency symbols (e.g., BTC,ETH,SOL).

#### Request Body
None

### Request Example
```bash
curl -H "X-Payment: 0x<tx_hash>" https://agents.krumpybot.com/crypto/prices?symbols=BTC,ETH
```

### Response
#### Success Response (200)
- **prices** (array) - An array of objects, each containing the cryptocurrency symbol, its current price, and the timestamp.

#### Response Example
```json
[
  {
    "symbol": "BTC",
    "price": 34500.50,
    "timestamp": "2023-10-27T10:00:00Z"
  },
  {
    "symbol": "ETH",
    "price": 1800.75,
    "timestamp": "2023-10-27T10:00:00Z"
  }
  // ... more cryptocurrencies
]
```

#### Error Response (402)
- **x402Version** (string) - The version of the x402 protocol.
- **accepts** (array) - An array detailing the payment options required.

#### Error Response Example (402)
```json
{
  "x402Version": "1",
  "accepts": [
    {
      "maxAmountRequired": "2000",
      "currency": "USDC",
      "network": "Base"
    }
  ]
}
```
```

--------------------------------

### GET /indicators/rsi/{symbol}

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Returns the Relative Strength Index (RSI) technical indicator with buy/sell signal interpretation.

```APIDOC
## GET /indicators/rsi/{symbol}

### Description
Returns the Relative Strength Index (RSI) technical indicator with buy/sell signal interpretation.

### Method
GET

### Endpoint
https://agents.krumpybot.com/indicators/rsi/{symbol}

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The trading symbol for which to get the RSI (e.g., AAPL).

#### Query Parameters
- **period** (integer) - Optional - The period for the RSI calculation (default is 14).

#### Request Body
None

### Request Example
```bash
curl -H "X-Payment: 0xabc123...txhash" "https://agents.krumpybot.com/indicators/rsi/AAPL?period=14"
```

### Response
#### Success Response (200)
- **symbol** (string) - The trading symbol.
- **period** (integer) - The period used for RSI calculation.
- **rsi** (number) - The calculated Relative Strength Index value.
- **signal** (string) - Interpretation of the RSI value (e.g., 'Buy', 'Sell', 'Hold').
- **timestamp** (string) - The timestamp when the indicator was calculated.

#### Response Example
```json
{
  "symbol": "AAPL",
  "period": 14,
  "rsi": 65.5,
  "signal": "Hold",
  "timestamp": "2024-01-15T20:00:00.000Z"
}
```
```

--------------------------------

### Forex Rates Endpoint

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/README.md

Get current exchange rates for various currency pairs. Payment is required via x402.

```APIDOC
## GET /forex/rates

### Description
Retrieves current exchange rates for a specified base currency against other currencies. Payment is required via x402.

### Method
GET

### Endpoint
`/forex/rates`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **base** (string) - Optional - The base currency (e.g., USD, EUR). Defaults to USD if not provided.

#### Request Body
None

### Request Example
```bash
curl -H "X-Payment: 0x<tx_hash>" https://agents.krumpybot.com/forex/rates?base=EUR
```

### Response
#### Success Response (200)
- **base** (string) - The base currency.
- **rates** (object) - An object containing currency pairs and their current exchange rates.

#### Response Example
```json
{
  "base": "USD",
  "rates": {
    "EUR": 0.92,
    "GBP": 0.81,
    "JPY": 150.00
  }
}
```

#### Error Response (402)
- **x402Version** (string) - The version of the x402 protocol.
- **accepts** (array) - An array detailing the payment options required.

#### Error Response Example (402)
```json
{
  "x402Version": "1",
  "accepts": [
    {
      "maxAmountRequired": "2000",
      "currency": "USDC",
      "network": "Base"
    }
  ]
}
```
```

--------------------------------

### Stocks Quote Endpoint

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/README.md

Get the latest quote for a specific stock symbol. This endpoint requires payment via x402.

```APIDOC
## GET /stocks/quote/:symbol

### Description
Retrieves the latest stock quote for a specified symbol. Payment is required via x402.

### Method
GET

### Endpoint
`/stocks/quote/:symbol`

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The stock symbol (e.g., AAPL, GOOG).

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -H "X-Payment: 0x<tx_hash>" https://agents.krumpybot.com/stocks/quote/AAPL
```

### Response
#### Success Response (200)
- **symbol** (string) - The stock symbol.
- **price** (number) - The current stock price.
- **timestamp** (string) - The timestamp of the quote.

#### Response Example
```json
{
  "symbol": "AAPL",
  "price": 170.50,
  "timestamp": "2023-10-27T10:00:00Z"
}
```

#### Error Response (402)
- **x402Version** (string) - The version of the x402 protocol.
- **accepts** (array) - An array detailing the payment options required.

#### Error Response Example (402)
```json
{
  "x402Version": "1",
  "accepts": [
    {
      "maxAmountRequired": "5000",
      "currency": "USDC",
      "network": "Base"
    }
  ]
}
```
```

--------------------------------

### Demo Endpoint

Source: https://github.com/krumpybot/financial-oracles-gateway/blob/main/README.md

A free endpoint to test the x402 payment flow without requiring any payment.

```APIDOC
## GET /demo/quote

### Description
Provides a free stock quote for AAPL, intended for testing the x402 payment flow. No payment is required for this endpoint.

### Method
GET

### Endpoint
`/demo/quote`

### Parameters
None

### Request Example
```bash
curl https://agents.krumpybot.com/demo/quote
```

### Response
#### Success Response (200)
- **symbol** (string) - The stock symbol.
- **price** (number) - The current stock price.
- **timestamp** (string) - The timestamp of the quote.

#### Response Example
```json
{
  "symbol": "AAPL",
  "price": 170.50,
  "timestamp": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### GET /fred/indicators

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Returns key economic indicators from the Federal Reserve Economic Data (FRED) database with latest values and trends.

```APIDOC
## GET /fred/indicators

### Description
Returns key economic indicators from the Federal Reserve Economic Data (FRED) database with latest values and trends.

### Method
GET

### Endpoint
https://agents.krumpybot.com/fred/indicators

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -H "X-Payment: 0xabc123...txhash" https://agents.krumpybot.com/fred/indicators
```

### Response
#### Success Response (200)
- **count** (integer) - The number of indicator categories returned.
- **categories** (array) - A list of indicator categories.
- **indicators** (object) - An object containing detailed indicator data by category.
  - **gdp** (array) - Real GDP data.
    - **series_id** (string) - FRED series ID.
    - **name** (string) - Name of the indicator.
    - **latest_value** (number) - The latest reported value.
    - **latest_date** (string) - The date of the latest value.
    - **change** (number) - The change from the previous period.
  - **inflation** (array) - Inflation data (e.g., CPI).
    - **series_id** (string) - FRED series ID.
    - **name** (string) - Name of the indicator.
    - **latest_value** (number) - The latest reported value.
    - **latest_date** (string) - The date of the latest value.
    - **change** (number) - The change from the previous period.
  - **employment** (array) - Employment data (e.g., Unemployment Rate).
    - **series_id** (string) - FRED series ID.
    - **name** (string) - Name of the indicator.
    - **latest_value** (number) - The latest reported value.
    - **latest_date** (string) - The date of the latest value.
    - **change** (number) - The change from the previous period.
- **timestamp** (string) - The timestamp when the data was retrieved.

#### Response Example
```json
{
  "count": 15,
  "categories": ["gdp", "inflation", "employment", "rates"],
  "indicators": {
    "gdp": [
      {
        "series_id": "GDPC1",
        "name": "Real GDP",
        "latest_value": 22538.4,
        "latest_date": "2023-10-01",
        "change": 1.2
      }
    ],
    "inflation": [
      {
        "series_id": "CPIAUCSL",
        "name": "Consumer Price Index",
        "latest_value": 308.742,
        "latest_date": "2023-12-01",
        "change": 0.3
      }
    ],
    "employment": [
      {
        "series_id": "UNRATE",
        "name": "Unemployment Rate",
        "latest_value": 3.7,
        "latest_date": "2023-12-01",
        "change": 0.0
      }
    ]
  },
  "timestamp": "2024-01-15T20:00:00.000Z"
}
```
```

--------------------------------

### GET /treasury/debt

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Returns current US national debt levels, debt held by public vs intragovernmental, and 30-day trends.

```APIDOC
## GET /treasury/debt

### Description
Returns current US national debt levels, debt held by public vs intragovernmental, and 30-day trends.

### Method
GET

### Endpoint
https://agents.krumpybot.com/treasury/debt

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -H "X-Payment: 0xabc123...txhash" https://agents.krumpybot.com/treasury/debt
```

### Response
#### Success Response (200)
- **total_debt** (integer) - The total US national debt.
- **debt_held_public** (integer) - The portion of debt held by the public.
- **intragovernmental** (integer) - The portion of debt held intragovernmentally.
- **record_date** (string) - The date of the debt record.
- **change_30d** (integer) - The change in total debt over the last 30 days.
- **trend** (array) - Historical total debt data.
  - **date** (string) - The date of the record.
  - **total** (integer) - The total debt on that date.
- **timestamp** (string) - The timestamp when the data was retrieved.

#### Response Example
```json
{
  "total_debt": 34000000000000,
  "debt_held_public": 26500000000000,
  "intragovernmental": 7500000000000,
  "record_date": "2024-01-14",
  "change_30d": 150000000000,
  "trend": [
    { "date": "2024-01-14", "total": 34000000000000 },
    { "date": "2024-01-07", "total": 33925000000000 },
    { "date": "2023-12-31", "total": 33850000000000 }
  ],
  "timestamp": "2024-01-15T20:00:00.000Z"
}
```
```

--------------------------------

### Convert Currency (Bash)

Source: https://context7.com/krumpybot/financial-oracles-gateway/llms.txt

Converts a specified amount from one currency to another using live exchange rates. Requires a payment header.

```bash
# Convert 1000 USD to EUR
curl -H "X-Payment: 0xabc123...txhash" \
  "https://agents.krumpybot.com/forex/convert?from=USD&to=EUR&amount=1000"
```