@2sio/sdk
Advanced tools
Typed client for 2s — the (most) everything API. Pay-per-call AI-agent data APIs, settled in USDC on Base or Solana via x402.
Typed TypeScript client for 2s.io — the (most) everything API. Pay-per-call AI-agent data APIs on Base or Solana via x402.
No signup, no API keys, no credit card on file. Sign for whichever rail you hold USDC on (EIP-3009 on Base, partial SPL transfer on Solana), hit any endpoint, get back typed JSON. Settles in ~2 seconds. Prices start at $0.001 per call. The endpoint catalog is constantly expanding — 2s is an open-ended experiment in maximally-comprehensive agent infrastructure.
npm install @2sio/sdk
Verify any endpoint works before funding a wallet. trial: true makes free calls (one per endpoint per hour, no key, no signup):
import { TwoS } from '@2sio/sdk'
const trial = new TwoS({ trial: true })
const { data } = await trial.validate.iban({ iban: 'GB82WEST12345698765432' })
console.log(data.items[0].valid) // real result; once/hour/endpoint, then throws TwoSError('TRIAL_EXHAUSTED')
Drop trial and pass a privateKey/signer (below) to pay per call for unlimited access.
Most endpoints are reads. Watchers flip that: arm one once and we POST you a signed callback the instant something happens — a wallet moves, a 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) and retried with exponential backoff, with a pull backstop via watchers.status.
const { data } = await client.watchers.stockPrice({
ticker: 'AAPL', conditionType: 'above', threshold: 250,
callbackUrl: 'https://your-agent.app/hooks/aapl',
})
console.log(data.items[0].watcherId) // we POST your payload here the moment AAPL crosses $250
// also: client.watchers.cryptoAddressActivity({...}), client.watchers.earnings({...})
Prefer connecting an MCP host by URL? There's a hosted MCP at
https://2s.io/mcp. Note that a hosted signer means your key transits 2s's servers — this SDK is the more private path (your key never leaves your machine), so prefer it when you can.
import { TwoS } from '@2sio/sdk'
const client = new TwoS({
privateKey: 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? }
Most endpoints return the normalized envelope — a consistent wrapper so you don't learn a different shape per endpoint:
{
ok: true,
items: T[], // results — always an array (single-result lookups return a 1-element array)
total: number | null, // total matching rows upstream, or null when the upstream doesn't report one
page?: { number, size, pages },
source: { provider, url, license },
meta?: { ... } // endpoint-specific extras (mode flags, query echoes, etc.)
}
A handful of endpoints keep a custom shape by design and advertise responseShape: "legacy" in /api/directory and x-2s-response-shape in the OpenAPI spec: the enrichment endpoints (e.g. person.crossRegistry, geo.nearby, *.profile, *.screen) return per-source { found, error, ... } blocks rather than a flat items array, and the binary endpoints (barcode.generate, countdown.gif, image.compress, ai.screenshot) return raw bytes (result.data is a Uint8Array). The Normalized<T> type is exported for the normalized ones.
1.0 makes the normalized envelope the stable, advertised contract. Breaking change: the per-endpoint *Response types (PatentsSearchResponse, DnsLookupResponse, etc.) have been removed — those endpoints now return Normalized (their typed methods return R<Normalized> / R<Normalized<T>>). If you imported one of those types, switch to Normalized from @2sio/sdk and read result.data.items. Legacy-shape endpoints (enrichment per-source blocks, binary Uint8Array responses, account.balance, url.*) keep their existing types and are flagged responseShape: "legacy" on the discovery surfaces. No runtime behavior changed — this is a types-only cut.
If you'd rather build the signer yourself (e.g. for a custodial KMS-backed wallet), pass signer directly:
import { privateKeyToAccount } from 'viem/accounts'
const client = new TwoS({ signer: privateKeyToAccount('0x...') })
The SDK auto-detects 402 responses, signs the payment, retries, and returns typed data. Your private key never leaves your process.
An ever-expanding catalog of 560+ endpoints across 112+ groups (live count in the directory), currently spanning:
ai.council)lock), durable message queues (queue), cron-style scheduled callbacks (schedule), pub/sub topics with fan-out (pubsub)store)watchers)resolve)New groups and endpoints land regularly. 2s is an open-ended experiment in maximally-comprehensive agent infrastructure — the goal is to keep widening the surface autonomous software can reach behind a single payment-aware interface.
Live catalog: https://2s.io/api/directory · OpenAPI 3.1: https://2s.io/api/openapi · Machine manifest: https://2s.io/.well-known/x402.
config.maxPriceUsd. There is no default cap (maxPriceUsd defaults to Infinity) — set it to opt into a ceiling.onPaymentRequested hook lets you approve/deny each call.const client = new TwoS({
signer,
maxPriceUsd: 0.05,
onPaymentRequested: async ({ url, amountUsd }) => {
console.log(`approve ${amountUsd} USDC for ${url}?`)
return amountUsd < 0.02
},
})
Every call returns { data, settlement?, costUsd, endpoint }. settlement carries the x402 receipt; data is the typed response body.
const result = await client.law.sanctionsCheck({ query: 'John Doe' })
console.log(result.data.items) // typed
console.log(result.settlement?.txHash) // basescan tx
console.log(result.costUsd) // 0.0048
TwoSError — HTTP error from 2s.io (4xx/5xx after payment).PaymentRefusedError — local refusal: price exceeded maxPriceUsd or the onPaymentRequested hook returned false.x402 mode settles on Base or Solana mainnet (USDC on both). On Base the Coinbase CDP facilitator handles verify + settle; on Solana the SDK signs a partial SPL USDC transfer. Pay on whichever rail your wallet holds USDC — no facilitator config required from your side.
MIT. See LICENSE.
@2sio/mcp — exposes every endpoint as an MCP tool for Claude Desktop / AgentKit / any MCP host.FAQs
Typed TypeScript client for 2s.io — 575+ pay-per-call tools for AI agents — ground-truth data, AI gateway, and agent infra (storage, locks, queues, watchers). x402 USDC on Base/Solana, no API keys, upto usage billing, free trials.
The npm package @2sio/sdk receives a total of 388 weekly downloads. As such, @2sio/sdk popularity was classified as not popular.
We found that @2sio/sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.