{
  "markdown": "# 2s.io SDK\n\n[![smithery badge](https://smithery.ai/badge/twosio/mcp)](https://smithery.ai/servers/twosio/mcp)\n[![2s-io/sdk MCP server](https://glama.ai/mcp/servers/2s-io/sdk/badges/score.svg)](https://glama.ai/mcp/servers/2s-io/sdk)\n\n**Client SDK + MCP server for [2s.io](https://2s.io) — the (most) everything API. One pay-per-call API giving AI agents ground-truth data across hundreds of endpoints, paid per call in USDC on Base or Solana via [x402](https://x402.org).**\n\nThis repo ships SDKs for every major agent-development language plus an MCP server for any MCP-aware host:\n\n| Language | Package | Install | Status |\n|---|---|---|---|\n| **TypeScript / Node** | [`@2sio/sdk`](./packages/2s-sdk) | `npm install @2sio/sdk` | ✅ x402 |\n| **TypeScript / Node** | [`@2sio/mcp`](./packages/2s-mcp) | `npx @2sio/mcp` | ✅ MCP server, x402 |\n| **Python** | [`2sio`](./packages/python) | `pip install 2sio` | ✅ x402 |\n| **Python / LangChain** | [`langchain-twosio`](./packages/python-langchain) | `pip install langchain-twosio` | ✅ Tool adapters |\n| **Python / LlamaIndex** | [`llama-index-tools-twosio`](./packages/python-llamaindex) | `pip install llama-index-tools-twosio` | ✅ Tool adapters |\n| **Go** | [`github.com/2s-io/sdk/packages/go`](./packages/go) | `go get github.com/2s-io/sdk/packages/go` | 🚧 x402 wire-up pending |\n| **Rust** | [`twosio`](./packages/rust) | `cargo add twosio` | 🚧 x402 wire-up pending |\n\nNo accounts. No API keys. No credit cards. Buyers sign an EIP-3009 USDC authorization (Base) or an SPL USDC transfer (Solana) on-the-fly, the facilitator verifies + settles in ~2 seconds on mainnet, and the API returns typed data. Prices start at $0.0025/call.\n\n## 🎁 Try before you buy — free, no wallet\n\nWant to confirm an endpoint actually works before funding anything? Every endpoint serves **one free real call per endpoint per hour** — no key, no wallet, no signup. Add `?trial=1` (or header `X-2s-Trial: 1`), or flip the SDK into trial mode:\n\n```ts\nimport { TwoS } from '@2sio/sdk'\nconst trial = new TwoS({ trial: true })            // no key required\nconst { data } = await trial.validate.iban({ iban: 'GB82WEST12345698765432' })\nconsole.log(data.items[0].valid)                    // real result; response meta.trial = { free: true, ... }\n```\n\n```python\nfrom twosio import TwoS\ntrial = TwoS(trial=True)                            # no key required\nprint(trial.validate.iban(iban=\"GB82WEST12345698765432\").data[\"items\"][0][\"valid\"])\n```\n\n```bash\ncurl \"https://2s.io/api/validate/iban?iban=GB82WEST12345698765432&trial=1\"\n```\n\n```bash\nnpx -y @2sio/mcp --trial      # MCP host with free trial calls; or set TWOS_TRIAL=1\n```\n\nThe trial runs the **real handler** and returns real data. Once the hourly trial is used, the endpoint returns the normal `402` — drop `trial` and pass a `privateKey`/`signer` to pay per call for unlimited access.\n\n## 🔔 Watchers — get woken up, don't poll\n\nMost endpoints are reads. **Watchers** flip that: arm one once and 2s pushes you a **signed callback the instant something happens** — a wallet moves on Base/Ethereum/Bitcoin, a US stock crosses your price, a company reports earnings. No polling loop, no wasted calls. Flat **$0.05** to arm; callbacks are EIP-191-signed (verify offline), retried with exponential backoff, with a pull backstop via `watchers.status`. A new class of stateful, agent-native primitives.\n\n```ts\nconst client = new TwoS({ privateKey: process.env.EVM_PRIVATE_KEY })\nconst { data } = await client.watchers.stockPrice({\n  ticker: 'AAPL', conditionType: 'above', threshold: 250,\n  callbackUrl: 'https://your-agent.app/hooks/aapl',\n})\n// also: watchers.cryptoAddressActivity, watchers.earnings — see https://2s.io/watchers\n```\n\n## Hosted MCP (connect by URL)\n\nDon't want to install anything? Point any MCP host at the hosted server:\n\n```\nhttps://2s.io/mcp\n```\n\nStreamable-HTTP; set header `X-EVM-Private-Key: 0x…` (USDC on Base) and 2s signs + settles x402 per call. **Tradeoff: a hosted signer means your private key transits 2s's infrastructure — for keys that never leave your machine, run `npx @2sio/mcp` locally or use the SDK above (the more private, secure path).**\n\n## 30-second demo\n\n**TypeScript:**\n\n```ts\nimport { TwoS } from '@2sio/sdk'\nimport { privateKeyToAccount } from 'viem/accounts'\n\nconst client = new TwoS({ signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`) })\n\nconst { data } = await client.patents.search({ q: 'neural network', limit: 5 })\nconsole.log(data.items[0].title) // normalized envelope: { ok, items, total, source, meta? }\n```\n\n**Python:**\n\n```python\nfrom eth_account import Account\nfrom twosio import TwoS\n\nclient = TwoS(signer=Account.from_key(os.environ[\"EVM_PRIVATE_KEY\"]))\nr = client.patents.search(q=\"neural network\", limit=5)\nprint(r.data[\"hits\"][0][\"title\"])\n```\n\n## 30-second Claude Desktop install\n\n```json\n{\n  \"mcpServers\": {\n    \"2sio\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@2sio/mcp\"],\n      \"env\": { \"EVM_PRIVATE_KEY\": \"0x...\" }\n    }\n  }\n}\n```\n\nRestart 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 — paying per call, no human in the loop.\n\n## What's behind the API\n\n575+ endpoints across 113+ groups (live count in the [directory](https://2s.io/api/directory)) across:\n\n- **AI:** webpage summarization, translation, typed extraction, image description, transcription, screenshots\n- **Agent primitives:** persistent key-value memory, agent-to-agent marketplace (register / discover / review), knowledge-delta (\"what changed in X since date Y\"), atomic batch settlement\n- **Control plane:** wallet-scoped agent infrastructure — distributed locks/leases, durable message queues, cron-style scheduled callbacks, pub/sub topics with fan-out\n- **Storage:** pay-per-call wallet-keyed persistence — key-value, documents, vector / full-text search, private blob upload\n- **Watchers (push, not poll):** arm once, get a signed callback the instant a wallet moves, a stock crosses a price, or a company reports earnings\n- **Security:** CVE lookup (NVD + CISA KEV + EPSS), email-security, HTTP security headers, password-exposure (HIBP), RPKI, CT logs, IOC reputation, CWE / ATT&CK / CAPEC, exploit availability\n- **Patents & trademarks:** USPTO Open Data Portal search + full file-wrapper detail + document list; trademark full-text search + status\n- **Law:** federal/state case search, citation verification, OFAC sanctions screening, Federal Register, CFR & USC, opinions, dockets\n- **Government:** Congress bills/votes/members, FEC campaign finance, FDA drug/device/food events + recalls, OSHA/MSHA, USAspending, EPA facilities, USGS water (50+ endpoints)\n- **Finance & treasury:** SEC EDGAR company facts, filings, insider trades, 13F holdings; US Treasury debt + cash; stock quotes; FX rates\n- **Vehicles & aviation:** VIN decode, recalls, complaints, investigations (NHTSA); aircraft registry, airports, flight data\n- **Health & medical:** ICD-10 / HCPCS / RxNorm, hospital quality, Medicare provider + open-payments, clinical trials, drug pricing\n- **Business & registries:** Secretary-of-State entity search, GLEIF LEI entity-match, KYB screening, IRS nonprofit search, bank routing\n- **Energy, agriculture, maritime & telecom:** energy prices & production, USDA agriculture, soil surveys, vessel & port data, phone/number intelligence\n- **Geo / weather / earth:** forward + reverse geocoding, US weather by ZIP, NOAA tides, sunrise/sunset, climate stations, recent earthquakes, IP geolocation (single + bulk)\n- **Space:** launches, close approaches, satellites, exoplanets, sky-tonight, space weather\n- **Internet:** DNS lookup, RDAP whois, TLS inspection, URL unfurl (Open Graph), URL → clean Markdown\n- **Wikipedia / academic papers:** summaries, multi-source paper search (arXiv + PubMed + Semantic Scholar)\n- **Crypto:** multi-chain address validation (BTC, ETH, SOL, LTC, TRX, XRP, BCH), live EVM gas oracle\n- **Economics & labor:** BLS series, inflation, World Bank indicators, ACS demographics, occupations, USAJOBS, College Scorecard\n- **Data & utilities:** 10+ validators (IBAN, email, phone, VAT…), EDI parsing, ISO codes, unit/currency conversion, hashing, image compression, barcode/QR, countdown GIFs\n\nLive catalog: <https://2s.io/api/directory>. OpenAPI 3.1: <https://2s.io/api/openapi>. Machine-discovery manifest: <https://2s.io/.well-known/x402>.\n\n## Safety\n\n- 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 ceiling.\n- Every x402 payment is a single-use EIP-3009 authorization with a 60-second deadline. No allowances are issued; a leaked key can only spend what's in the wallet at the moment of signing, only at advertised prices.\n- Optional `onPaymentRequested` hook lets callers approve/deny each call programmatically.\n\n## Repo layout\n\n```\npackages/\n├── 2s-sdk/             @2sio/sdk — typed TypeScript client\n├── 2s-mcp/             @2sio/mcp — MCP server (depends on 2s-sdk)\n├── python/             2sio — Python client\n├── python-langchain/   langchain-twosio — LangChain tool adapters\n├── python-llamaindex/  llama-index-tools-twosio — LlamaIndex tool adapters\n├── go/                 Go client (x402 wire-up pending)\n└── rust/               Rust client (x402 wire-up pending)\nexamples/sdk/   minimal paying-agent samples + Claude Desktop wiring\n```\n\n## License\n\nMIT. See [LICENSE](./packages/2s-sdk/LICENSE).\n\n## Links\n\n- API site: <https://2s.io>\n- npm:\n  - <https://www.npmjs.com/package/@2sio/sdk>\n  - <https://www.npmjs.com/package/@2sio/mcp>\n- x402 protocol: <https://x402.org>\n- MCP protocol: <https://modelcontextprotocol.io>\n",
  "bytes": 9769,
  "sha": "e1a7ccc2b3d0737d7005a7f94e9aa05c4916c447d362336d813412f6230d0353",
  "repo_slug": "2s-io/sdk",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_2s_io_mcp_5d002d47/readme"
}