FilingDelta docs

Overview

Base URL: https://filingdelta.xyz. Every route returns JSON unless noted. Free routes (samples, catalog, status, updates) need no payment, no account and no key. Paid routes answer an unpaid request with HTTP 402 and the price, then return the card once it is paid. Ids are uppercase (AMD), and an unknown id returns 404 before any payment, so you are never charged for a card that does not exist.

Every card is a summary of what changed in a published document, cited to its source. Not investment advice. Check the free content_hash in /catalog: a card only changes when its source does, so buy again only when the hash has changed.

Endpoints

Prices are per call in USDC on Base. Each family above takes an id from /catalog; the example ids are real. Free routes:

• /catalog: every covered id with price, network, payTo, as_of, next_update and content_hash. JSON for Accept: application/json or ?format=json, an HTML page for browsers.
• /sample/ routes: a free sample of every card type (links in the table). Filing samples show one change in full and the others as teasers; macro and CPI samples are a teaser with part of the latest release’s items (items_hidden says how many are withheld); central-bank samples are the previous meeting as a full card plus the latest meeting’s date and content_hash.
• /status (JSON: /status.json), /updates (the changelog, JSON), /digest and the feeds /feed.json, /feed.atom, /feed.rss.
• /.well-known/x402 (x402 discovery), /openapi.json, /llms.txt.
• POST /request with JSON {"what": "..."} (optional price_usd, frequency, contact): ask for coverage we do not have. It is free and rate limited.

Pay with x402

An unpaid request to a paid route returns 402 with the payment requirements in the PAYMENT-REQUIRED header (base64 JSON) and a readable copy in the body:

$ curl -i https://filingdelta.xyz/delta/AMD
HTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6Mi…
content-type: application/json

{"error":"payment_required", "message":"This card is paid. Pay with x402: …",
 "x402Version":2, "scheme":"exact", "network":"eip155:8453",
 "amount":"50000", "asset":"0x833589fC…2913", "payTo":"0x6d41a1B6…2f2a",
 "maxTimeoutSeconds":300, "price_usd":"0.05",
 "resource":"https://filingdelta.xyz/delta/AMD", "free_sample":"https://filingdelta.xyz/sample/AMD", … }

1. Decode the header. accepts[0] has scheme exact, network eip155:8453 (Base), amount in USDC base units (6 decimals, so 50000 is $0.05), the USDC asset contract, payTo and maxTimeoutSeconds.
2. Sign an exact payment of that amount to payTo with an x402 v2 client.
3. Retry the same request with the header PAYMENT-SIGNATURE: <base64 PaymentPayload>. The card comes back as JSON, and the receipt is in the PAYMENT-RESPONSE header.

The paid routes are listed on the x402 Bazaar, so agents can discover them there. A lowercase or padded id of a known card gets a 301 to the canonical uppercase id before the paywall, with no charge.

Credit key

If you would rather not use a wallet, buy a credit pack by card at /buy ($5 for 100 cards; $20 for 450 cards (includes 50 bonus cards)). You get an API key, shown once. Send it as an X-API-Key header on any paid route and you get the same card JSON as an x402 payment. Each card uses 1 credit, and a bundle uses 1 credit per card in it. Credits do not expire. GET /buy/balance with your key returns {"credits_remaining": …}; without a valid key it returns 401. If a paid route still answers 402 although you sent a key, the key is not recognised: check it here. To use your credits by clicking, open /credits.

Connect over MCP

Endpoint: https://filingdelta.xyz/mcp, Streamable HTTP (JSON-RPC 2.0 over POST). The free tools need no sign-in. In an MCP client that supports remote servers, add a custom server with that URL; opening it in a browser shows an error because it only speaks POST. The Official MCP Registry name is xyz.filingdelta/filingdelta.

$ curl -s https://filingdelta.xyz/mcp \
    -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
         "params":{"name":"sample_delta","arguments":{"ticker":"AMD"}}}'

Send tools/list for the current list of tools; /about describes them. Paid tools use x402: an unpaid tools/call returns a normal result with isError: true and the x402 PaymentRequired in structuredContent, the same object as the PAYMENT-REQUIRED header of the matching HTTP route. Retry the same tools/call with the PaymentPayload in params._meta["x402/payment"] (or with the header PAYMENT-SIGNATURE). The receipt comes back in result._meta["x402/payment-response"]. A client that cannot pay can still use every free tool.

Error codes

Browsers asking for HTML on an unknown path get a short page with the same 404 status; every other client gets the JSON above.

Something not working as described here? Contact us.