2sio (Python)
Python client for 2s.io — 575+ pay-per-call tools for AI agents: more ground-truth data than any other x402 API, a full AI gateway (chat, image, multi-model consensus), and agent infrastructure (wallet-scoped storage, locks, queues, schedules, watchers). USDC on Base or Solana via x402.
upto billing (new on 2s): AI endpoints also accept the x402 upto scheme — authorize the quoted max, get settled for your actual usage (a real on-chain example settled at 1/42nd of the quote). Exact-scheme calls work unchanged.
pip install 2sio
🎁 Try before you buy — free, no wallet
Verify any endpoint before funding a wallet. trial=True makes free calls (one per endpoint per hour, no key, no signup):
from twosio import TwoS
trial = TwoS(trial=True)
print(trial.validate.iban(iban="GB82WEST12345698765432").data["items"][0]["valid"])
# real result; once/hour/endpoint, then raises TwoSError(code="TRIAL_EXHAUSTED")
Pass private_key=... (below) to pay per call for unlimited access.
🔔 Watchers — get woken up, don't poll
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. Flat $0.05 to arm; callbacks are EIP-191-signed (verify offline) and retried with exponential backoff, with a pull backstop via watchers.status.
res = client.watchers.stock_price(
ticker="AAPL", conditionType="above", threshold=250,
callbackUrl="https://your-agent.app/hooks/aapl",
)
print(res.data["items"][0]["watcherId"]) # we POST your payload here the moment AAPL crosses $250
# also: client.watchers.crypto_address_activity(...), client.watchers.earnings(...)
Quick start
import os
from twosio import TwoS
# private_key is an EVM key (0x...) holding USDC on Base mainnet.
client = TwoS(private_key=os.environ["EVM_PRIVATE_KEY"])
r = client.patents.search(q="neural network", limit=5)
print(r.data["hits"][0]["title"])
print("paid:", r.cost_usd, "USDC, tx:", r.settlement["tx_hash"])
Settles on Base mainnet in ~2 seconds. Prices start at $0.0025/call.
If you'd rather construct the signer yourself (e.g. for a custodial KMS-backed wallet), pass it directly:
from eth_account import Account
signer = Account.from_key(os.environ["EVM_PRIVATE_KEY"])
client = TwoS(signer=signer)
What's included
An ever-expanding catalog of 575+ endpoints across 113+ groups (live count in the directory), namespaced by group — spanning AI (incl. multi-model consensus), agent primitives, control plane (distributed locks, durable queues, scheduled callbacks, pub/sub), storage (key-value / documents / vectors / private blobs), watchers (signed push callbacks), security (CVE / KEV / EPSS, IOC, exploits), identity resolution (ID crosswalks), patents & trademarks, law & sanctions, government & public records, finance & treasury, vehicles & aviation, health & medical, business & GLEIF/KYB, energy & agriculture, maritime & telecom, geo / weather / earth, space, science & papers, property & licenses, internet, crypto, music & news, text redaction & PII scrubbing, and data validators / utilities:
client.patents.search(q="...")
client.security.cve(id="CVE-2024-3094")
client.crypto.address_validate(chain="eth", address="0xd8dA...")
client.ai.summarize(url="https://example.com")
client.law.sanctions_check(name="John Smith")
client.business.entity_match(name="Acme Corp")
client.geocode.address(query="350 5th Ave, New York, NY")
client.weather.zip(zip="94103")
# ... and 530+ more
Full catalog: https://2s.io/api/directory. OpenAPI: https://2s.io/api/openapi.
Safety
- The client refuses to sign payments above
max_price_usd. There is no default cap (max_price_usddefaults toinf) — set it to opt into a ceiling. - Optional
on_payment_requestedhook for per-call approval.
client = TwoS(
private_key=os.environ["EVM_PRIVATE_KEY"],
max_price_usd=0.05,
on_payment_requested=lambda info: info["amount_usd"] < 0.02,
)
Errors
TwoSError— HTTP error from 2s.io.PaymentRefusedError— local refusal (price cap or hook).
License
MIT.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file 2sio-1.82.0.tar.gz.
File metadata
- Download URL: 2sio-1.82.0.tar.gz
- Upload date:
- Size: 75.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.11.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
36b768b9f653437c9013df4a4008b92a8e68fbd4a39d4bf5cf23609433d5d325
|
|
| MD5 |
1c235e90545c384cd7ccd463257703ab
|
|
| BLAKE2b-256 |
e40f33f8ca02a57189aefa804b13f5b0105b12e6e698c8e39df6705af56daa3d
|
File details
Details for the file 2sio-1.82.0-py3-none-any.whl.
File metadata
- Download URL: 2sio-1.82.0-py3-none-any.whl
- Upload date:
- Size: 72.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.11.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c98351b3399a1e2b6b7a1830f58e423acbd1b449bf66f73525b4d9cfa63091e1
|
|
| MD5 |
1586f2c75582be636f7d3f25b3570503
|
|
| BLAKE2b-256 |
7062aa4136fefb185f5b49e4c389e95870d55530636a95b8b644a9c4f91328b4
|
