{"openapi":"3.1.0","info":{"title":"2s — the (most) everything API","version":"1","summary":"The (most) everything API.","description":"The (most) everything API for AI agents: 575+ pay-per-call endpoints on one origin. More live, ground-truth data than any other x402 service — public records, finance & SEC filings, crypto & web3, security & CVEs, legal, medical, weather, geocoding, and B2B/EDI. A full AI gateway: chat, image, and multi-model consensus across every major model, priced per request in the 402 before you pay. And agent infrastructure with no account: wallet-scoped storage (kv/docs/vectors/files), locks, queues, scheduled callbacks, pub/sub, and watchers that push signed webhooks when the world changes. Pay per call in USDC on Base or Solana via x402 — no API keys, no signup, no subscription. The first x402 API with upto billing: on AI endpoints, authorize the quoted max and settle only your actual usage. Try before you buy: add ?trial=1 (or header X-2s-Trial: 1) to any endpoint for one free real call per endpoint per hour — no wallet needed. New endpoints land constantly.","contact":{"name":"2s","url":"https://2s.io","email":"alley@2s.io"},"x-logo":{"url":"https://2s.io/icon-512.png","altText":"2s"},"x-guidance":"Pay-per-call REST API for AI agents — hundreds of endpoints returning ground-truth data (US public records, company & legal identifiers, finance/SEC, crypto/web3, security & CVEs, medical codes, weather & geocoding, agriculture, energy, maritime, music, and more). Every endpoint is paid per call in USDC via x402 (Base or Solana) — no API key, no signup. Call any endpoint with no auth to get a 402 PaymentRequirements envelope, sign it (EIP-3009 on Base, partial SPL transfer on Solana), and retry with the PAYMENT-SIGNATURE header. Add ?trial=1 for one free real call per endpoint per hour to test before paying. To discover the right endpoint: GET https://2s.io/api/directory for the full catalog, or GET https://2s.io/api/search/endpoints?q=<natural-language task> for a ranked match. Per-call price is on each operation as x-payment-info (from $0.001). Batch up to 50 calls behind one payment via POST https://2s.io/api/batch/run."},"servers":[{"url":"https://2s.io"}],"components":{"responses":{"BadRequest":{"description":"Bad request — invalid parameters."},"PaymentRequired":{"description":"Payment required. Body contains the x402 PaymentRequirements envelope with a multi-network accepts array; the per-call price is in accepts[].amount (and on the operation as x-2s-price). Sign for whichever rail you hold USDC on (EIP-3009 for Base, partial SPL transfer for Solana) and retry with the PAYMENT-SIGNATURE header (X-PAYMENT also accepted for v1 clients).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PaymentRequiredV2"}}}},"MethodNotAllowed":{"description":"Method not allowed — see `Allow` header for the supported method."},"ServerError":{"description":"Internal server error."},"UpstreamError":{"description":"Upstream provider error."}},"parameters":{"TrialMode":{"name":"trial","in":"query","required":false,"description":"Try before you buy. Set to 1 for one free real call per endpoint per hour — no wallet or payment needed — to verify the endpoint before paying. Equivalent to sending the \"X-2s-Trial: 1\" request header. Works on every endpoint.","schema":{"type":"integer","enum":[1]}}},"securitySchemes":{"x402Payment":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 protocol v2: base64-encoded PaymentPayload. Call any paid endpoint without auth to receive a 402 with a multi-network PaymentRequirements envelope. Sign for either rail: EIP-3009 transferWithAuthorization (Base USDC) OR a partial SPL token transfer (Solana USDC). Retry with PAYMENT-SIGNATURE header. X-PAYMENT is also accepted for v1 buyer clients. See https://x402.org."}},"schemas":{"Source":{"type":"object","description":"Provenance of the data: upstream provider, source URL, and license.","properties":{"provider":{"type":"string","description":"Upstream data provider."},"url":{"type":"string","description":"Source URL or documentation link."},"license":{"type":"string","description":"License / usage terms for the data."}}},"CallMeta":{"type":"object","description":"Per-call meta envelope — endpoint id, cost, caller kind, settlement details."},"X402PaymentRequiredV2":{"type":"object","description":"x402 v2 PaymentRequired envelope. Pick any entry from accepts[], sign for that rail, retry with the PAYMENT-SIGNATURE header.","required":["x402Version","accepts"],"properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string","description":"Human-readable reason payment is required."},"resource":{"type":"string","description":"The resource URL being purchased."},"accepts":{"type":"array","description":"Payment requirement options, one per supported network (Base USDC, Solana USDC).","items":{"type":"object","required":["scheme","network","amount","asset","payTo","maxTimeoutSeconds"],"properties":{"scheme":{"type":"string","enum":["exact"]},"network":{"type":"string","description":"CAIP-2 network id, e.g. \"eip155:8453\" (Base) or \"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp\"."},"amount":{"type":"string","description":"Price in atomic asset units (USDC has 6 decimals)."},"asset":{"type":"string","description":"Asset contract address / mint."},"payTo":{"type":"string","description":"Treasury address to pay."},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object","description":"Rail-specific extras (EVM: EIP-712 domain name/version; Solana: feePayer).","additionalProperties":true}}}},"extensions":{"type":"object","description":"Optional discovery metadata (e.g. bazaar input/output schemas).","additionalProperties":true}}}}},"paths":{"/api/news/hn-item":{"get":{"tags":["news"],"summary":"Fetch a specific Hacker News item (story, comment, job...","description":"Fetch a specific Hacker News item (story, comment, job, poll) by its numeric ID. Returns id, type, author, time (unix + ISO), title, URL, text, score, descendant count, kid count, parent (for comments), dead/deleted flags, canonical news.ycombinator.com URL.","operationId":"news_hn-item","deprecated":false,"security":[{"x402Payment":[]}],"responses":{"200":{"description":"Normalized envelope: items = [HN item] (story/comment/job/poll by id); total = 1, or items = [] / total = 0 when the id is unknown.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","nullable":true},"by":{"type":"string","nullable":true},"time":{"type":"integer","nullable":true},"timeIso":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"text":{"type":"string","nullable":true},"score":{"type":"integer","nullable":true},"descendantsCount":{"type":"integer","nullable":true},"kidsCount":{"type":"integer"},"parent":{"type":"integer","nullable":true},"deleted":{"type":"boolean"},"dead":{"type":"boolean"},"hnUrl":{"type":"string","format":"uri"}},"required":["id","type","by","time","timeIso","title","url","text","score","descendantsCount","kidsCount","parent","deleted","dead","hnUrl"],"additionalProperties":false}},"total":{"type":"integer","nullable":true,"description":"Total matching rows upstream; null when unknown."},"source":{"$ref":"#/components/schemas/Source"}},"required":["ok","items","total","source"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/CallMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"$ref":"#/components/responses/UpstreamError"}},"x-2s-id":"news.hn-item","x-2s-version":null,"x-2s-price":{"usd":0.003},"x-2s-accepts":["x402"],"x-2s-response-shape":"normalized","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"id","in":"query","required":true,"description":"Unique identifier of the record to fetch.","schema":{"type":"integer","minimum":1,"maximum":1000000000}},{"$ref":"#/components/parameters/TrialMode"}]}},"/api/news/hn-search":{"get":{"tags":["news"],"summary":"Full-text search across all of Hacker News (via the Algolia...","description":"Full-text search across all of Hacker News (via the Algolia HN API). Search stories or comments by keyword, sorted by relevance or by date (newest first). Filter by tags (story/comment/ask_hn/show_hn/poll) and by author. Each hit: title, URL, author, points, comment count, story/comment text, created time, and canonical HN URL. Net-new vs news.hn-top (curated feeds) and news.search (general news).","operationId":"news_hn-search","deprecated":false,"security":[{"x402Payment":[]}],"responses":{"200":{"description":"Normalized: items = search hits; meta.nbHits = total matches upstream.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"objectId":{"type":"string","nullable":true},"type":{"type":"string"},"title":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"author":{"type":"string","nullable":true},"points":{"type":"number","nullable":true},"numComments":{"type":"number","nullable":true},"storyText":{"type":"string","nullable":true},"commentText":{"type":"string","nullable":true},"createdAt":{"type":"string","nullable":true},"storyId":{"type":"number","nullable":true},"hnUrl":{"type":"string"}},"required":["objectId","type","title","url","author","points","numComments","storyText","commentText","createdAt","storyId","hnUrl"],"additionalProperties":false}},"total":{"type":"integer","nullable":true,"description":"Total matching rows upstream; null when unknown."},"source":{"$ref":"#/components/schemas/Source"},"meta":{"type":"object","properties":{"query":{"type":"string"},"nbHits":{"type":"number"}},"required":["query","nbHits"],"additionalProperties":false}},"required":["ok","items","total","source"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/CallMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"$ref":"#/components/responses/UpstreamError"}},"x-2s-id":"news.hn-search","x-2s-version":null,"x-2s-price":{"usd":0.003},"x-2s-accepts":["x402"],"x-2s-response-shape":"normalized","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"query","in":"query","required":false,"description":"Search keywords (may be empty when filtering by tags/author).","schema":{"type":"string","maxLength":400,"default":""}},{"name":"tags","in":"query","required":false,"description":"Tags.","schema":{"type":"string","enum":["story","comment","ask_hn","show_hn","poll"]}},{"name":"sort","in":"query","required":false,"description":"Field to sort results by.","schema":{"type":"string","enum":["relevance","date"]}},{"name":"author","in":"query","required":false,"description":"Restrict to one HN author.","schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":50}},{"$ref":"#/components/parameters/TrialMode"}]}},"/api/news/hn-top":{"get":{"tags":["news"],"summary":"Hacker News feed of items.","description":"Hacker News feed of items. Pass kind = top (default) | new | best | ask | show | job to pick the feed. Returns each item's id, type, author, time (unix + ISO), title, URL, text (for self-posts), score, descendant + kid counts, parent (for comments), dead/deleted flags, and canonical news.ycombinator.com URL. Default limit = 30, max 100. Useful for tech-sentiment + topic tracking.","operationId":"news_hn-top","deprecated":false,"security":[{"x402Payment":[]}],"responses":{"200":{"description":"Normalized envelope: items = Hacker News feed items; total = null (HN feeds report no true count); meta.kind echoes the requested feed.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","nullable":true},"by":{"type":"string","nullable":true},"time":{"type":"integer","nullable":true},"timeIso":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"text":{"type":"string","nullable":true},"score":{"type":"integer","nullable":true},"descendantsCount":{"type":"integer","nullable":true},"kidsCount":{"type":"integer"},"parent":{"type":"integer","nullable":true},"deleted":{"type":"boolean"},"dead":{"type":"boolean"},"hnUrl":{"type":"string","format":"uri"}},"required":["id","type","by","time","timeIso","title","url","text","score","descendantsCount","kidsCount","parent","deleted","dead","hnUrl"],"additionalProperties":false}},"total":{"type":"integer","nullable":true,"description":"Total matching rows upstream; null when unknown."},"source":{"$ref":"#/components/schemas/Source"},"meta":{"type":"object","properties":{"kind":{"type":"string"}},"required":["kind"],"additionalProperties":false}},"required":["ok","items","total","source"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/CallMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"$ref":"#/components/responses/UpstreamError"}},"x-2s-id":"news.hn-top","x-2s-version":null,"x-2s-price":{"usd":0.003},"x-2s-accepts":["x402"],"x-2s-response-shape":"normalized","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"kind","in":"query","required":false,"description":"Kind.","schema":{"type":"string","enum":["top","new","best","ask","show","job"],"default":"top"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}},{"$ref":"#/components/parameters/TrialMode"}]}},"/api/news/hn-user":{"get":{"tags":["news"],"summary":"Hacker News user profile by username.","description":"Hacker News user profile by username. Returns id, account creation time (unix + ISO), karma, the about/bio text, number of items submitted, and the canonical news.ycombinator.com profile URL. Unknown user returns an empty result.","operationId":"news_hn-user","deprecated":false,"security":[{"x402Payment":[]}],"responses":{"200":{"description":"Normalized: items = [HN user] or [] when unknown.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"created":{"type":"number","nullable":true},"createdIso":{"type":"string","nullable":true},"karma":{"type":"number","nullable":true},"about":{"type":"string","nullable":true},"submittedCount":{"type":"number","nullable":true},"hnUrl":{"type":"string","nullable":true}},"required":["id","created","createdIso","karma","about","submittedCount","hnUrl"],"additionalProperties":false}},"total":{"type":"integer","nullable":true,"description":"Total matching rows upstream; null when unknown."},"source":{"$ref":"#/components/schemas/Source"}},"required":["ok","items","total","source"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/CallMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"$ref":"#/components/responses/UpstreamError"}},"x-2s-id":"news.hn-user","x-2s-version":null,"x-2s-price":{"usd":0.003},"x-2s-accepts":["x402"],"x-2s-response-shape":"normalized","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"username","in":"query","required":true,"description":"HN username, e.g. pg, dang.","schema":{"type":"string","minLength":1,"maxLength":40}},{"$ref":"#/components/parameters/TrialMode"}]}},"/api/news/search":{"get":{"tags":["news"],"summary":"Live news search. Returns recent headlines with title, URL...","description":"Live news search. Returns recent headlines with title, URL, snippet, publisher source, relative age, and a breaking-news flag — real-time coverage past any model training cutoff. Supports count (1-20), offset, country (2-letter), and freshness (pd=past day, pw=past week, pm=past month, py=past year). Use for current events, market-moving developments, monitoring, and \"what happened with X\" questions. For general web results see /api/search/web; for Hacker News specifically see /api/news/hn-top.","operationId":"news_search","deprecated":false,"security":[{"x402Payment":[]}],"responses":{"200":{"description":"Normalized envelope: items = recent news headlines (publisher, age, breaking flag); total = null (Brave reports no count); meta.query echoes the search.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"},"description":{"type":"string","nullable":true},"source":{"type":"string","nullable":true,"description":"Publisher hostname."},"age":{"type":"string","nullable":true,"description":"Relative recency, e.g. \"5 hours ago\"."},"breaking":{"type":"boolean"},"thumbnail":{"type":"string","nullable":true}},"required":["title","url","description","source","age","breaking","thumbnail"],"additionalProperties":false}},"total":{"type":"integer","nullable":true,"description":"Total matching rows upstream; null when unknown."},"source":{"$ref":"#/components/schemas/Source"},"meta":{"type":"object","properties":{"query":{"type":"string"}},"required":["query"],"additionalProperties":false}},"required":["ok","items","total","source"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/CallMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"$ref":"#/components/responses/UpstreamError"}},"x-2s-id":"news.search","x-2s-version":null,"x-2s-price":{"usd":0.0225},"x-2s-accepts":["x402"],"x-2s-response-shape":"normalized","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.022500"},"protocols":[{"x402":{}}]},"parameters":[{"name":"q","in":"query","required":true,"description":"News query.","schema":{"type":"string","minLength":1,"maxLength":400}},{"name":"count","in":"query","required":false,"description":"Count.","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}},{"name":"offset","in":"query","required":false,"description":"Number of results to skip before returning (pagination offset).","schema":{"type":"integer","minimum":0,"maximum":9,"default":0}},{"name":"country","in":"query","required":false,"description":"Country name or ISO country code.","schema":{"type":"string","pattern":"^[a-zA-Z]{2}$"}},{"name":"freshness","in":"query","required":false,"description":"Freshness.","schema":{"type":"string","enum":["pd","pw","pm","py"]}},{"$ref":"#/components/parameters/TrialMode"}]}}}}