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
Metadata
1 maintainer
Release files for 2sio 1.82.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| 2sio-1.82.0.tar.gz | 75.7 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| 2sio-1.82.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 148.5 kB
Release files / 2sio-1.82.0.tar.gz
| Download URL | 2sio-1.82.0.tar.gz |
|---|---|
| Size | 75.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
36b768b9f653437c9013df4a4008b92a8e68fbd4a39d4bf5cf23609433d5d325
|
|
BLAKE2b-256 checksum How to use checksums |
e40f33f8ca02a57189aefa804b13f5b0105b12e6e698c8e39df6705af56daa3d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Release files / 2sio-1.82.0-py3-none-any.whl
| Download URL | 2sio-1.82.0-py3-none-any.whl |
|---|---|
| Size | 72.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c98351b3399a1e2b6b7a1830f58e423acbd1b449bf66f73525b4d9cfa63091e1
|
|
BLAKE2b-256 checksum How to use checksums |
7062aa4136fefb185f5b49e4c389e95870d55530636a95b8b644a9c4f91328b4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Security for 2sio 1.82.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
