llama-index-tools-twosio

LlamaIndex tools for 2s.io — pay-per-call AI agent APIs on Base via the x402 protocol.

No signup. No API keys. No monthly fees. Just a USDC-funded EVM wallet on Base mainnet. Each call settles per-request in USDC.

pip install llama-index-tools-twosio

import asyncio
import os
from llama_index_tools_twosio import get_twosio_tools
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.anthropic import Anthropic

tools = get_twosio_tools(private_key=os.environ["EVM_PRIVATE_KEY"])
agent = FunctionAgent(tools=tools, llm=Anthropic(model="claude-haiku-4-5"))
response = asyncio.run(agent.run("Find recent patents for 'neural network beamforming'."))
print(response)

The agent picks the right 2s.io endpoint, calls it, pays in USDC, and returns the result — transparent to your model.

What's in the box

Each tool wraps one 2s.io endpoint with a clear description and a typed pydantic schema. The curated set covers the highest-leverage workflows:

The full 2s.io catalog has 39 endpoints. To use one not in the curated set, build a tool manually:

from llama_index_tools_twosio import twosio_tool
from llama_index_tools_twosio._endpoints import EndpointSpec, Param
from twosio import TwoS

client = TwoS(private_key=os.environ["EVM_PRIVATE_KEY"])

custom = twosio_tool(client, EndpointSpec(
    name="twosio_dns_lookup",
    short_name="dns.lookup",
    description="Resolve a hostname against public DNS resolvers.",
    sdk_path=("dns", "lookup"),
    params=[
        Param("name", str, "Hostname to resolve."),
        Param("type", str, "Record type (A | AAAA | MX | TXT | NS).", required=False),
    ],
))

The full live catalog: https://2s.io/api/directory · OpenAPI: https://2s.io/api/openapi.

Filters

# Only the legal tools:
tools = get_twosio_tools(private_key=KEY, include=["law.case-search", "law.sanctions-check"])

# Everything except the LLM-backed (Tier 2) ones:
tools = get_twosio_tools(private_key=KEY, exclude=["ai.summarize"])

How payment works

Every tool call runs through the underlying 2sio SDK, which:

1. Hits the 2s.io endpoint.
2. Receives HTTP 402 Payment Required with an x402 envelope (price + recipient + EIP-3009 challenge).
3. Signs the transferWithAuthorization with your private key.
4. Retries with the signed payload.
5. Returns the response. The meta.settlement block in each result includes the on-chain tx hash.

You only pay for successful calls.

License

MIT.

Links

• 2s.io: https://2s.io
• Source: https://github.com/2s-io/sdk
• Issues: https://github.com/2s-io/sdk/issues
• Underlying SDK: 2sio on PyPI