# Filedge — Full API Reference for LLMs and AI Agents # https://filedge.io | Version: 1.0.0 # This document is machine-readable. For human docs see https://filedge.io/docs ## Overview Filedge is a financial document intelligence API that transforms SEC EDGAR filings and earnings call transcripts into structured JSON data optimised for agent consumption. Every call to POST /v1/parse costs $0.05 USDC, paid on-demand via the x402 micropayment protocol on Base mainnet (no subscription, no API key required — just a wallet). Supported document types: - 10-Q Quarterly report (revenue, net income, EPS, segments, guidance, risk flags) - 10-K Annual report (full year financials, business description, risk factors) - 8-K Material event (earnings releases, officer appointments, acquisitions) - form4 SEC Form 4 — insider trades (buy/sell transactions + signal summary) - transcript Earnings call transcript (tone, topics, forward signals, analyst Q&A) --- ## Endpoint POST https://filedge.io/v1/parse Headers (required for paid requests): Content-Type: application/json X-PAYMENT: # generated by x402 client SDK (see §Payment) --- ## Request Schema All fields are JSON. Field names are case-sensitive. | Field | Type | Required | Values / Notes | |----------|--------|----------------------|-------------------------------------------------------------| | source | string | yes | "edgar" | "transcript" | "url" | | type | string | yes (edgar only) | "10-Q" | "10-K" | "8-K" | "form4" | | ticker | string | yes (edgar/trans.) | Uppercase ticker, e.g. "AAPL", "TSLA", "MSFT" | | period | string | no (default: latest) | "latest" | "YYYY-QN" (e.g. "2024-Q2") | "YYYY" (10-K) | | url | string | yes (url source) | Direct EDGAR or public document URL | ### source="edgar" Fetches the filing from SEC EDGAR and parses it. ### source="transcript" Fetches the latest earnings call transcript for the given ticker. ### source="url" Fetches and parses the document at the provided URL directly. --- ## Response Schema — 10-Q / 10-K (quarterly/annual financials) { "document_type": "10-Q", "ticker": "AAPL", "company_name": "Apple Inc.", "period": "Q2 2025", "filed_date": "2025-05-02", "fiscal_year_end": "September", "financials": { "revenue_usd_cents": 9535800000000, // integer, USD cents "gross_profit_usd_cents": 4339300000000, "operating_income_usd_cents": 2982500000000, "net_income_usd_cents": 2436000000000, "eps_basic": 1.65, // float "eps_diluted": 1.65, "shares_outstanding": 15204137000, "cash_and_equivalents_usd_cents": 3745200000000, "total_debt_usd_cents": 9761400000000, "free_cash_flow_usd_cents": 2431900000000 }, "segments": [ {"name": "iPhone", "revenue_usd_cents": 4629900000000}, {"name": "Services", "revenue_usd_cents": 2629800000000}, {"name": "Mac", "revenue_usd_cents": 792000000000}, {"name": "iPad", "revenue_usd_cents": 567600000000}, {"name": "Wearables, Home & Accessories", "revenue_usd_cents": 709500000000} ], "guidance": { "next_quarter_revenue_low_usd_cents": null, "next_quarter_revenue_high_usd_cents": null, "commentary": "Company expects Services to grow double digits YoY." }, "risk_flags": [ "FX headwinds in Greater China (-7% YoY)", "Ongoing EU Digital Markets Act compliance costs" ], "yoy_change_pct": { "revenue": 4.3, "net_income": 7.9, "eps_diluted": 8.6 }, "source_url": "https://www.sec.gov/Archives/edgar/data/320193/...", "parsed_at": "2025-05-03T10:22:11Z" } --- ## Response Schema — 8-K (material event) { "document_type": "8-K", "ticker": "MSFT", "company_name": "Microsoft Corporation", "filed_date": "2025-04-25", "item_codes": ["2.02", "9.01"], "event_summary": "Microsoft reported Q3 FY2025 earnings. Revenue $70.1B (+15% YoY), EPS $3.46.", "key_data": { "revenue_usd_cents": 7010000000000, "net_income_usd_cents": 2570000000000, "eps_diluted": 3.46 }, "officer_changes": [], "acquisitions": [], "exhibits": [ {"exhibit": "99.1", "description": "Press Release — Q3 FY2025 Earnings", "url": "https://..."} ], "source_url": "https://www.sec.gov/Archives/edgar/data/789019/...", "parsed_at": "2025-04-25T21:05:44Z" } --- ## Response Schema — Form 4 (insider trades) { "document_type": "form4", "ticker": "TSLA", "company_name": "Tesla, Inc.", "reporting_person": "Elon R. Musk", "relationship": "CEO / 10% owner", "filed_date": "2025-03-15", "transactions": [ { "date": "2025-03-12", "transaction_code": "S", // S=sale, P=purchase, A=award, D=disposition "shares": 1000000, "price_usd_cents": 17542, // per share "total_value_usd_cents": 175420000000, "shares_owned_after": 411624784, "direct_or_indirect": "D" // D=direct, I=indirect } ], "signal": { "net_shares_bought": -1000000, "net_shares_sold": 1000000, "summary": "Insider SOLD 1,000,000 shares (~$175.4M). Net disposition." }, "source_url": "https://www.sec.gov/Archives/edgar/data/1318605/...", "parsed_at": "2025-03-15T18:33:02Z" } --- ## Response Schema — Transcript (earnings call) { "document_type": "transcript", "ticker": "TSLA", "company_name": "Tesla, Inc.", "quarter": "Q1 2025", "call_date": "2025-04-23", "tone": { "overall": "cautiously_optimistic", // positive | cautiously_optimistic | neutral | negative "management_confidence": 0.71, // 0.0–1.0 "forward_looking_ratio": 0.43 }, "topics": ["FSD autonomy", "energy storage growth", "margin recovery", "Cybertruck ramp"], "forward_signals": [ "Expects vehicle deliveries to grow in H2 2025", "FSD take-rate accelerating; robotaxi launch targeted late 2025", "Energy division revenue expected to exceed auto in 2026" ], "analyst_qa": [ { "analyst": "Dan Levy — Barclays", "question": "Can you quantify the ASP impact from higher mix of lower-priced models?", "answer_summary": "Management cited pricing discipline offset by cost reductions. Margins expected to recover as Cybertruck scales." } ], "key_quotes": [ "We are very close to full autonomy — it's a matter of months, not years. — Elon Musk" ], "source_url": "https://...", "parsed_at": "2025-04-23T23:11:59Z" } --- ## Worked Examples ### Example 1 — AAPL Latest 10-Q Request: POST /v1/parse {"source": "edgar", "type": "10-Q", "ticker": "AAPL", "period": "latest"} Expected response: Full quarterly financials for Apple's most recent 10-Q filing. ### Example 2 — TSLA Earnings Call Transcript Request: POST /v1/parse {"source": "transcript", "ticker": "TSLA"} Expected response: Parsed earnings transcript with tone analysis, topics, forward signals, analyst Q&A. ### Example 3 — MSFT 8-K (material event) Request: POST /v1/parse {"source": "edgar", "type": "8-K", "ticker": "MSFT", "period": "latest"} Expected response: Latest material event filing for Microsoft, including event type, officer changes, key financial data if earnings release. ### Example 4 — Insider Trade Form 4 Request: POST /v1/parse {"source": "edgar", "type": "form4", "ticker": "TSLA", "period": "latest"} Expected response: Latest Form 4 for Tesla with insider transaction details and net buy/sell signal. --- ## Payment Integration — x402 v2 Protocol All requests to POST /v1/parse require an upfront micropayment of $0.05 USDC. Payment details: Protocol: x402 v2 Network: eip155:8453 (Base mainnet) Asset: USDC — 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 Amount: 50000 (USDC has 6 decimal places → 50000 = $0.05) PayTo: 0xa98E17D26e1B3A51A10C79c2F52f78914E7D50EB How it works: 1. Client sends POST /v1/parse with no payment header. 2. Server responds HTTP 402 with a JSON payment requirements body. 3. Client SDK reads requirements, builds the X-PAYMENT header (signed EIP-712 message + tx data). 4. Client retries the request with X-PAYMENT header. 5. Server verifies payment on-chain, processes request, returns 200 + parsed JSON. ### Python Example (x402-python SDK) ```python import httpx from x402.client import wrap # pip install x402 # Wrap an httpx client — handles 402 flow automatically client = wrap( httpx.Client(), private_key="0xYOUR_PRIVATE_KEY", # wallet with Base mainnet USDC ) response = client.post( "https://filedge.io/v1/parse", json={ "source": "edgar", "type": "10-Q", "ticker": "AAPL", "period": "latest", }, ) print(response.status_code) # 200 data = response.json() print(data["financials"]["revenue_usd_cents"]) ``` ### curl Example (manual — for testing without SDK) ```bash # Step 1: Probe for payment requirements curl -s -X POST https://filedge.io/v1/parse \ -H "Content-Type: application/json" \ -d '{"source":"edgar","type":"10-Q","ticker":"AAPL","period":"latest"}' # → 402 with {"x402Version":2,"accepts":[...],"error":"Payment required"} # Step 2: Build X-PAYMENT header using x402 CLI, then retry curl -s -X POST https://filedge.io/v1/parse \ -H "Content-Type: application/json" \ -H "X-PAYMENT: " \ -d '{"source":"edgar","type":"10-Q","ticker":"AAPL","period":"latest"}' # → 200 with structured JSON ``` --- ## Error Codes | HTTP | error code | Meaning | |------|-------------------------|-----------------------------------------------------------| | 402 | payment_required | Missing or invalid X-PAYMENT header | | 400 | invalid_request | Missing required field or invalid field value | | 400 | unsupported_source | source must be edgar | transcript | url | | 400 | unsupported_type | type must be 10-Q | 10-K | 8-K | form4 | | 404 | filing_not_found | No filing found for ticker/period combination | | 422 | parse_error | Document fetched but could not be parsed | | 429 | rate_limit_exceeded | Too many requests — back off and retry | | 500 | internal_error | Unexpected server error — safe to retry after 5s | Error response body: { "error": "filing_not_found", "message": "No 10-Q found for ticker XYZ in period latest", "docs": "https://docs.filedge.io/errors/filing_not_found" } --- ## Rate Limits There are no hard per-key rate limits (the x402 payment acts as the economic rate limiter). Under high load the server may return HTTP 429; use exponential backoff starting at 1 second. Recommended max concurrency: 5 parallel requests per wallet address. --- ## Service Discovery GET /.well-known/x402.json — x402 service metadata (routes, payment requirements) GET /llms.txt — Short AI-readable summary GET /llms-full.txt — This document (full reference) GET /docs — OpenAPI / Swagger UI GET /health — Liveness probe {"status":"ok"} GET /sitemap.xml — Sitemap GET /robots.txt — Robots policy --- ## Monetisation / Agent Integration Notes - No API key needed — payment is the auth. - Compatible with any x402 v2 client library (Python, TypeScript, Go). - Ideal for autonomous agents: the 402→pay→retry loop requires zero human interaction. - All monetary values in responses are integers (USD cents) to avoid float precision issues. - Responses are deterministic for the same filing; caching by (ticker, type, period) is safe. --- Contact / Support: https://filedge.io | @filedge on X