# Agent Utility Suite

> SEC filings and web data for AI agents: read any section of a US public company's 10-K or 10-Q (risk factors, MD&A, …) since 2001, its latest 8-K events and press releases, and a free index of its filings; turn any web page into clean Markdown; profile a domain's email setup. No accounts or API keys: pay per call in USDC with x402. Payments settle in USDC on Base (eip155:8453) using the x402 v2 HTTP payment protocol.

## How to call a tool

1. Send the request normally. The server answers 402 Payment Required with a base64 PAYMENT-REQUIRED header (the JSON body repeats it under `accepts`).
2. Sign one `accepts` entry with an x402 v2 client and retry with the PAYMENT-SIGNATURE header (X-PAYMENT also works).
3. The response carries a PAYMENT-RESPONSE receipt. You are only charged if the call succeeds: invalid input returns 400 and the payment is not settled.

Libraries such as @x402/fetch (TypeScript) handle steps 1–3 automatically.

## MCP server

The same tools are available as a remote MCP server (Streamable HTTP) at https://x402-agent-api.onrender.com/mcp. Calling a tool without payment returns an error result whose structuredContent is the x402 PaymentRequired; retry with the signed payment in `_meta["x402/payment"]`. The receipt is returned in `_meta["x402/payment-response"]`. MCP clients wrapped with @x402/mcp pay automatically. Invalid arguments and failed calls are not charged.

## Free tool

- [sec_list_filings](https://x402-agent-api.onrender.com/api/v1/sec-list-filings): Free, no payment needed. Lists a US public company's 10-K (annual), 10-Q (quarterly) and 8-K (material event) filings from SEC EDGAR, newest first: filing date, fiscal year and period, sec.gov link, the sections sec_filing_section can extract from each report (Risk Factors, MD&A, Business, Legal Proceedings, Market Risk, Cybersecurity), and the event items of each 8-K (earnings 2.02, executive changes 5.02, deals 1.01, cybersecurity incidents 1.05, …). Every filing carries `next_call`: the exact paid tool call, with arguments and price, that returns its text. Use it to check what exists before paying, to find a specific year or event, or to track new filings. Filter by form and date (back to 2001); up to 50 filings per call. Look up by stock ticker or CIK. Rate-limited per client.
  Example: POST https://x402-agent-api.onrender.com/api/v1/sec-list-filings with JSON body {"ticker":"AAPL","forms":["10-K","8-K"],"limit":2}

## Paid tools

- [sec_filing_section](https://x402-agent-api.onrender.com/api/v1/sec-filing-section): Answers questions like "What are Tesla's risk factors?", "What did Apple's MD&A say about margins?" or "How has Microsoft's cybersecurity disclosure changed since 2023?". Returns exactly one section of a US public company's 10-K (annual) or 10-Q (quarterly) report from SEC EDGAR as clean text, ready for an LLM: Risk Factors (Item 1A), Management's Discussion and Analysis (MD&A), Business, Legal Proceedings, Market Risk, or Cybersecurity. Look up by stock ticker or CIK. Defaults to the latest filing; pass `fiscal_year` (2001 on) for an earlier year's report, e.g. to compare how risk factors changed, or `accession_number` for an exact filing (the free sec_list_filings tool lists them, with the sections each one has). The table of contents, page numbers, hidden XBRL data and HTML are removed; tables are kept as readable rows. Includes the filing date, fiscal period, accession number and sec.gov link for citation. Use it for investment research, due diligence, competitor analysis or risk monitoring without downloading a 100-page filing. Sections up to 200,000 characters. If the filing's item only points elsewhere ("See Note 12"), you get 404 SECTION_INCORPORATED_BY_REFERENCE with that pointer, free. You are only charged when a result is returned: invalid input (400) and upstream failures (4xx/5xx) are not settled. Costs $0.02 USDC per call via x402.
  Example: POST https://x402-agent-api.onrender.com/api/v1/sec-filing-section with JSON body {"ticker":"AAPL","section":"risk_factors","form":"10-K"}
- [sec_recent_events](https://x402-agent-api.onrender.com/api/v1/sec-recent-events): Answers "What happened at this company lately?": did the CEO or CFO leave, what were the latest earnings, was there an acquisition, major contract or cyber incident. Returns a US public company's most recent 8-K filings from SEC EDGAR, newest first: the material events companies must report within four business days, such as earnings releases (Item 2.02), CEO, CFO and director changes (5.02), material agreements and acquisitions (1.01, 2.01), cybersecurity incidents (1.05), impairments, auditor changes and shareholder votes. Each event has its item codes with official titles, the 8-K text as clean prose, and the text of its press-release exhibits (EX-99), e.g. the full earnings release. Filter by item codes and filing date, or ask for one exact 8-K by `accession_number` (the free sec_list_filings tool lists them); up to 10 events per call. Look up by stock ticker or CIK. Use it for event monitoring, news and earnings agents, due diligence or trading research, with sec.gov links for citation. If no 8-K matches, you get 404 FILING_NOT_FOUND, free. You are only charged when a result is returned: invalid input (400) and upstream failures (4xx/5xx) are not settled. Costs $0.02 USDC per call via x402.
  Example: POST https://x402-agent-api.onrender.com/api/v1/sec-recent-events with JSON body {"ticker":"AAPL","items":["2.02"],"limit":1}
- [scrape_markdown](https://x402-agent-api.onrender.com/api/v1/scrape-markdown): Use it when an agent needs to read a web page: an article, documentation, a blog post, a product or pricing page, a news story. Fetches a public web page and returns its main content as clean Markdown, ready to put in an LLM context: scripts, styles, navigation, headers, footers and sidebars are removed, the article body is extracted (Readability), and links are made absolute. Returns the page title, the final URL after redirects and the character count; output is capped at 100,000 characters. Use it to read articles, docs, blog posts or product pages. Pages that need JavaScript to render may return little content. You are only charged when a result is returned: invalid input (400) and upstream failures (4xx/5xx) are not settled. Costs $0.005 USDC per call via x402.
  Example: POST https://x402-agent-api.onrender.com/api/v1/scrape-markdown with JSON body {"url":"https://example.com"}
- [domain_enrich](https://x402-agent-api.onrender.com/api/v1/domain-enrich): Answers "Who hosts this company's email, and is it configured properly?" and "Which SaaS tools does this company use?". Profiles a domain from live DNS and its website: MX records and the inferred email provider (Google Workspace, Microsoft 365, …), SPF and DMARC configuration and policy, services the domain has verified ownership with (from TXT records: Google, Microsoft, Stripe, Atlassian, …), whether the website is reachable over HTTPS, and stack and security headers (Server, X-Powered-By, HSTS, CSP). Use it for lead enrichment, email deliverability checks, vendor due diligence or security reviews. You are only charged when a result is returned: invalid input (400) and upstream failures (4xx/5xx) are not settled. Costs $0.005 USDC per call via x402.
  Example: POST https://x402-agent-api.onrender.com/api/v1/domain-enrich with JSON body {"domain":"stripe.com"}

## Machine-readable docs

- [MCP server](https://x402-agent-api.onrender.com/mcp): Streamable HTTP, tools paid per call with x402
- [MCP tool manifest](https://x402-agent-api.onrender.com/.well-known/mcp.json): tool schemas, prices and HTTP bindings
- [OpenAPI 3.0 spec](https://x402-agent-api.onrender.com/openapi.json): full request/response schemas with x402 pricing (`x-x402`)
- [Health](https://x402-agent-api.onrender.com/health): free liveness check