# PennyQuery

> Pay-per-call company data for AI agents, served over MCP (Streamable HTTP, no auth): company enrichment records and SEC EDGAR filings, financials and insider trades. Search and lookup are free; full records cost $0.01 USDC per successful call via x402 on Base Sepolia (testnet).

Status: PREVIEW. Payments run on the Base Sepolia testnet with test USDC, which has no monetary value. Interfaces and prices may change before a mainnet launch.

MCP endpoint: https://api.pennyquery.com/mcp
Human-readable overview: https://api.pennyquery.com/connect
Terms: https://api.pennyquery.com/terms
Privacy: https://api.pennyquery.com/privacy

## Tools

Tools are grouped by data category. Categories marked planned have no tools yet; don't call them.

### Company enrichment

- search_companies (free): case-insensitive substring search over company name, domain, industry and description. Input: `query` (2-100 chars), optional `limit` (default 10, max 25). Returns `{ count, companies: [{ name, domain, industry }] }`. Use it to resolve a partial name to a domain.
- get_company_enrichment (paid, $0.01): full record for one company: name, domain, industry, employee_count, description, last_updated (ISO 8601 UTC), source. Input: exactly one of `domain` (preferred; URLs are normalized) or `name` (exact, case-insensitive). Returns error `not_found` when no record exists.

### SEC EDGAR: lookup and filing index

- sec_lookup_company (free): resolve a ticker, company name or CIK to SEC registrants. Input: `query`. Returns `{ count, companies: [{ cik, ticker, name }] }` (up to 10). Covers current exchange-listed registrants.
- get_sec_filings (paid, $0.01): recent EDGAR filings, newest first, plus company metadata (tickers, exchanges, SIC code, state of incorporation, fiscal year end). Input: exactly one of `ticker` or `cik`, optional `form` (e.g. "10-K"), optional `limit` (default 10, max 50). Each filing has accession_number, form, filing_date, report_date, description and a sec.gov url.

### SEC EDGAR: financial statement data (10-K, 10-Q, 20-F XBRL)

- get_sec_financials (paid, $0.01): headline annual figures from the latest 10-K/20-F/40-F XBRL data: revenue, net_income, operating_income, eps_diluted, total_assets, total_liabilities, stockholders_equity, cash. Each metric carries its us-gaap concept, period, fiscal year, form, filed date and accession number, or null if not reported under the standard concept. Input: exactly one of `ticker` or `cik`. Quarterly data, point-in-time history, restatements, ratios, segments and notes are planned.

### SEC EDGAR: insider trading (Form 4)

- get_sec_insider_trades (paid, $0.01): insider transactions parsed from a company's recent Form 4 and 4/A filings, newest first. Input: exactly one of `ticker` or `cik`, optional `limit` (Form 4 filings to scan, default 10, max 20), optional `since` (YYYY-MM-DD), optional `codes` (transaction codes to keep, e.g. ["P", "S"]; filings with no matching rows are dropped). Each filing has accession_number, form, filing_date, url, period_of_report, owners (name, cik, is_director, is_officer, officer_title, is_ten_percent_owner), aff_10b5_1 (null on pre-2023 filings) and transactions: table (non_derivative or derivative), security, date, code, code_meaning, acquired_disposed (A/D), shares, price, value, shares_owned_after, direct_or_indirect, footnotes; derivative rows add exercise_price, exercise_date, expiration_date, underlying_security, underlying_shares. `summary` totals open-market purchases (P) and sales (S) in the returned original Form 4s (4/A amendments are listed but not summed) and counts distinct insiders. `coverage_from` is the oldest date in EDGAR's recent-filings list that was searched.

### SEC EDGAR: planned categories (not yet callable)

- Insider trading (Forms 3, 5): initial ownership statements and annual reports.
- Institutional holdings (13F-HR, 13D/G): manager positions and quarter-over-quarter changes.
- Material events (8-K): item-level parsing, e.g. 2.02 earnings and 1.05 cybersecurity incidents.
- Other: proxy and executive compensation (DEF 14A), BDC investments, money-market holdings (N-MFP), capital raising (S-3, 424B), and narrative sections (risk factors, MD&A) for NLP.

## Paying with x402

1. Call a paid tool (get_company_enrichment, get_sec_filings, get_sec_financials or get_sec_insider_trades) without payment. The result has `isError: true` and `_meta["x402/error"]` with `error: "PAYMENT_REQUIRED"` and an `accepts` list of payment requirements (scheme `exact`, network `eip155:84532`, USDC asset, amount in 6-decimal units, `payTo`).
2. Sign a payment for one of the requirements with an x402 client (for example `@x402/core` with `@x402/evm`, or `withX402Client` from `agents/mcp/x402`).
3. Repeat the call with the base64-encoded payment payload in the request `_meta["x402/payment"]`.
4. On success the result carries `_meta["x402/payment-response"]` with the settlement transaction.

You are charged only when the lookup succeeds. Invalid input and `not_found` are never charged. A rejected payment returns `_meta["x402/error"]` with a reason such as `INVALID_PAYMENT` or `invalid_exact_evm_insufficient_balance`.

## Notes

- Tools are read-only and idempotent.
- Rate limits: requests without a payment are limited to about 60 per minute per client IP; over the limit, /mcp returns HTTP 429 with `Retry-After`. Paid calls are limited to 120 per minute per paying wallet, checked after the payment verifies; over the limit the tool returns error `rate_limited` and the payment is not settled (not charged). SEC tools can also return `upstream_busy` when the shared SEC EDGAR budget is used up; retry after a few seconds (not charged).
- Enrichment data provenance: the enrichment table is a hand-curated sample of 5 fictional companies on reserved `.example` domains, each with `source: "seed:sample"`. It contains no third-party or licensed data, is not refreshed on a schedule, and is for testing the payment flow only. Each record's `source` and `last_updated` fields say where it came from and when it was last edited.
- SEC data comes live from data.sec.gov (U.S. government data, public domain) at the time of the call. It reflects what EDGAR has published, which can lag a company's own announcements; filings can be amended later. XBRL figures are as reported by the filer and are not audited or adjusted by this service.
- Not investment advice. Data is provided as is, with no uptime or accuracy guarantee. See https://api.pennyquery.com/terms.