2s.io SDK

👁 2s-io/sdk MCP server

Client SDK + MCP server for 2s.io — a unified JSON REST API for AI agents, paid per call in USDC on Base or Solana via x402.

This repo ships SDKs for every major agent-development language plus an MCP server for any MCP-aware host:

No 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.001/call.

🎁 Try before you buy — free, no wallet

Want 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:

import { TwoS } from '@2sio/sdk'
const trial = new TwoS({ trial: true }) // no key required
const { data } = await trial.validate.iban({ iban: 'GB82WEST12345698765432' })
console.log(data.items[0].valid) // real result; response meta.trial = { free: true, ... }

from twosio import TwoS
trial = TwoS(trial=True) # no key required
print(trial.validate.iban(iban="GB82WEST12345698765432").data["items"][0]["valid"])

curl "https://2s.io/api/validate/iban?iban=GB82WEST12345698765432&trial=1"

npx -y @2sio/mcp --trial # MCP host with free trial calls; or set TWOS_TRIAL=1

The 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.

Related MCP server: Omni Service Node

30-second demo

TypeScript:

import { TwoS } from '@2sio/sdk'
import { privateKeyToAccount } from 'viem/accounts'

const client = new TwoS({ signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`) })

const { data } = await client.patents.search({ q: 'neural network', limit: 5 })
console.log(data.items[0].title) // normalized envelope: { ok, items, total, source, meta? }

Python:

from eth_account import Account
from twosio import TwoS

client = TwoS(signer=Account.from_key(os.environ["EVM_PRIVATE_KEY"]))
r = client.patents.search(q="neural network", limit=5)
print(r.data["hits"][0]["title"])

30-second Claude Desktop install

{
 "mcpServers": {
 "2sio": {
 "command": "npx",
 "args": ["-y", "@2sio/mcp"],
 "env": { "EVM_PRIVATE_KEY": "0x..." }
 }
 }
}

Restart Claude. The model can now call patents.search, law.sanctions-check, ai.summarize, geocode.address, vehicle.vin-decode, agent.knowledge-delta, and 120+ other paid tools — paying per call, no human in the loop.

What's behind the API

180+ endpoints (live count in the directory) across:

• AI: webpage summarization, translation, typed extraction, image description, screenshots

• Agent primitives: persistent key-value memory, agent-to-agent marketplace (register / discover / review), knowledge-delta ("what changed in X since date Y")

• Patents: USPTO Open Data Portal search + full file-wrapper detail + document list

• Law: federal/state case search, citation verification, OFAC sanctions screening, Federal Register, opinions, US trademark full-text search + status (USPTO)

• Government: Congress bills/votes/members, FEC campaign finance, FDA drug/device/food events + recalls, OSHA/MSHA, USAspending, EPA facilities, USGS water

• Finance: SEC EDGAR company facts, filings, insider trades, 13F holdings; US Treasury debt + cash

• Vehicles: VIN decode, recalls, complaints, investigations (NHTSA)

• Geo / weather: forward + reverse geocoding, US weather by ZIP, NOAA tides, sunrise/sunset, climate stations, recent earthquakes, IP geolocation (single + bulk)

• Internet: DNS lookup, RDAP whois, URL unfurl (Open Graph), URL → clean Markdown

• Wikipedia / academic papers: summaries, multi-source paper search (arXiv + PubMed + Semantic Scholar)

• Crypto: multi-chain address validation (BTC, ETH, SOL, LTC, TRX, XRP, BCH), live EVM gas oracle

• Airports: lookup by IATA/ICAO, nearest-airport-to-coord (OurAirports CC0, ~85k airports)

• Utilities: hash computation, image compression, barcode/QR generation, countdown GIFs

• Census / education / health / jobs / nonprofits: ACS demographics, College Scorecard, hospital + medical-license lookup, USAJOBS + BLS, IRS nonprofit search

Live catalog: https://2s.io/api/directory. OpenAPI 3.1: https://2s.io/api/openapi. Machine-discovery manifest: https://2s.io/.well-known/x402.

Safety

• The SDK refuses to sign payments above a configurable maxPriceUsd (default $0.10).

• 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.

• Optional onPaymentRequested hook lets callers approve/deny each call programmatically.

Repo layout

packages/
├── 2s-sdk/ @2sio/sdk — typed TypeScript client
├── 2s-mcp/ @2sio/mcp — MCP server (depends on 2s-sdk)
├── python/ 2sio — Python client
├── python-langchain/ langchain-twosio — LangChain tool adapters
├── python-llamaindex/ llama-index-tools-twosio — LlamaIndex tool adapters
├── go/ Go client (x402 wire-up pending)
└── rust/ Rust client (x402 wire-up pending)
examples/sdk/ minimal paying-agent samples + Claude Desktop wiring

License

MIT. See LICENSE.

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

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• agent.knowledge-deltaA
• agent.marketplace.discoverA
• agent.marketplace.profileA
• agent.marketplace.registerB
• agent.marketplace.reviewA
• agent.memory.deleteA
• agent.memory.getA
• agent.memory.listA