sdk

Purpose

2s.io is a pay-per-call x402 API known as the "almost universal API." It provides AI agents with real data across hundreds of endpoints, with each call paid via USDC on Base or Solana. This repository provides SDKs for all major agent development languages, as well as an MCP server for any MCP-capable host.

Key Capabilities

The API covers 113+ groups and 575+ endpoints, including:

• AI: web page summarization, translation, typed extraction, image description, transcription, screenshots
• Agent primitives: persistent key-value memory, inter-agent marketplace (registration/discovery/rating), knowledge deltas ("what changed for X since date Y"), atomic batch settlement
• Control plane: wallet-scoped agent infrastructure—distributed locks/leases, persistent message queues, cron-style scheduled callbacks, pub/sub topics with fan-out
• Storage: pay-per-call wallet-keyed persistence—key-value, documents, vector/full-text search, private blob uploads
• Watchers (push instead of poll): arm once and receive signed callbacks immediately when a wallet moves, a stock breaks a price, or a company releases earnings
• Security: CVE lookup (NVD + CISA KEV + EPSS), email security, HTTP security headers, password breaches (HIBP), RPKI, CT logs, IOC reputation, CWE/ATT&CK/CAPEC, exploit availability
• Patents and trademarks: USPTO Open Data Portal search + full file wrapper details + document listings; trademark full-text search + status
• Legal: federal/state case search, citation validation, OFAC sanctions screening, Federal Register, CFR and USC, opinions, dockets
• Government: congressional bills/votes/members, FEC campaign finance, FDA drugs/devices/food incidents + recalls, OSHA/MSHA, USAspending, EPA facilities, USGS water (50+ endpoints)
• Finance and treasury: SEC EDGAR company facts, filings, insider transactions, 13F holdings; U.S. Treasury debt + cash; stock quotes; exchange rates
• Vehicles and aviation: VIN decoding, recalls, complaints, investigations (NHTSA); aircraft registration, airports, flight data
• Health and medical：ICD-10/HCPCS/RxNorm, hospital quality, Medicare providers + Open Payments, clinical trials, drug pricing
• Business & registration: Secretary of State entity search, GLEIF LEI entity matching, KYB screening, IRS nonprofit search, bank routing
• Energy, agriculture, maritime & telecommunications: energy prices and production, USDA agriculture, soil surveys, vessel and port data, phone/number intelligence
• Geography/weather/earth: forward + reverse geocoding, U.S. weather by ZIP, NOAA tides, sunrise/sunset, climate stations, recent earthquakes, IP geolocation (single + batch)
• Space: launches, close approaches, satellites, exoplanets, tonight's sky, space weather
• Internet: DNS lookup, RDAP whois, TLS inspection, URL expansion (Open Graph), URL → clean Markdown
• Wikipedia/academic papers: summaries, multi-source paper search (arXiv + PubMed + Semantic Scholar)
• Cryptocurrency: multi-chain address validation (BTC, ETH, SOL, LTC, TRX, XRP, BCH), real-time EVM gas oracle
• Economy & labor: BLS series, inflation, World Bank indicators, ACS demographics, occupations, USAJOBS, College Scorecard
• Data & utilities: 10+ validators (IBAN, email, phone, VAT…), EDI parsing, ISO codes, unit/currency conversion, hashing, image compression, barcode/QR, countdown GIF

How to use

No account, API key, or credit card required. The buyer instantly signs an EIP-3009 USDC authorization (Base) or SPL USDC transfer (Solana), the coordinator verifies + settles on mainnet in about 2 seconds, and the API returns typed data. Prices start at $0.0025/call.

Free trial: each endpoint offers one free real call per hour—no key, wallet, or registration required. Add ?trial=1(or the request header X-2s-Trial: 1), or switch the SDK to trial mode. Trial runs execute the real handler and return real data. After the hourly trial is used up, the endpoint returns the normal 402—remove trial and pass in privateKey/signer to get unlimited access on a pay-per-call basis.

Watchers: most endpoints are read operations. Watchers are the opposite: arm once, and 2s pushes signed callbacks when events occur—wallet movements on Base/Ethereum/Bitcoin, U.S. stocks breaking through prices, companies releasing earnings. No polling loops, no wasted calls. Arming costs a flat $0.05; callbacks use EIP-191 signatures (verifiable offline), retry with exponential backoff, and provide a pull fallback via watchers.status.

Hosted MCP (connect by URL): don't want to install anything? Point any MCP host at the hosted server. Use Streamable-HTTP; set the request header X-EVM-Private-Key: 0x…(USDC on Base), and 2s will sign + settle x402 for each call. Trade-off: a hosted signer means your private key passes through 2s's infrastructure—for keys that never leave your machine, run locally npx @2sio/mcp Or use the above SDK (a more private and secure path).

30-second Claude Desktop installation: restart Claude. The model can now call patents.search, law.sanctions-check, ai.summarize, geocode.address, vehicle.vin-decode, agent.knowledge-delta, security.cve, and 340+ other paid tools—pay per call, with no human intervention.

When to use

Suitable for developers who need to provide AI agents with real-world data, covering law, finance, government, health, geography, space, the internet, and many other domains. Especially suitable for agent applications that need pay-per-call and do not want to manage API keys or accounts.

Limitations

• The SDK refuses to sign payments above a configurable maxPriceUsd. There is no default cap (maxPriceUsd defaults to Infinity)—set it to opt into a cap.
• Each x402 payment is a single-use EIP-3009 authorization with a 60-second deadline. No allowances are issued; a leaked key can only spend the amount in the wallet at signing time, and only at the advertised price.
• The optional onPaymentRequested hook allows the caller to programmatically approve/reject each call.
• The signer hosted with MCP means the private key passes through 2s infrastructure; running locally is safer.

Links

• API site:https://2s.io
• npm：https://www.npmjs.com/package/@2sio/sdk、https://www.npmjs.com/package/@2sio/mcp
• x402 protocol:https://x402.org
• MCP protocol:https://modelcontextprotocol.io
• Live directory:https://2s.io/api/directory
• OpenAPI 3.1：https://2s.io/api/openapi
• Machine discovery manifest:https://2s.io/.well-known/x402
• License: MIT, see LICENSE.