Vaaya for Python

Call paid services through one account, read receipts, and give customer agents their own keys and spending limits. Python 3.9 or later; the core client uses only the standard library.

Install

python -m pip install vaaya

Set VAAYA_API_KEY to your key from API keys.

from vaaya import Vaaya

vaaya = Vaaya()  # Reads VAAYA_API_KEY.
r = vaaya.one.search({"query": "recent advances in battery recycling"})
print(r["data"], r["charged_cents"])

This search has a default ceiling of 5¢. Charges and balances preserve fractional cents. Keep the key in your server environment.

Call a service

r = vaaya.use("exa/search", {"query": "battery recycling", "numResults": 5},
              max_cost_cents=5, idempotency_key="research-request-123")
service = vaaya.catalog.get("exa/search")  # Schema, price, and rail.
plan = vaaya.consult("Find battery recycling companies in Germany")  # 1¢.
# Read plan["message"] and plan["calls"] before running suggested calls.

catalog.discover(query) searches the catalog for free. one.scrape, one.crawl, one.find, one.enrich, and one.search_deep are shortcuts over use.

Wait for a job

started = vaaya.one.crawl("https://example.com", max_pages=20)
if started.get("job_id"):
    job = vaaya.result(started["job_id"], wait=True, timeout=120)
    print(job["status"], job["result"])

Polling is free. A timeout stops waiting; it does not cancel the server's job. The client is synchronous. Run it in a worker thread when calling from an async app.

Manage agents

agent = vaaya.agents.create(external_id="customer-42", label="Support agent",
                            ceiling_cents=500, period="month")
# Store agent["key"] now; create and rotate return the secret once.
vaaya.agents.update(agent["id"], paused=True)
vaaya.agents.update(agent["id"], ceiling_cents=2000, paused=False)
rotated = vaaya.agents.rotate(agent["id"])
vaaya.agents.revoke(agent["id"])

These writes require the account's primary key. vaaya.agents() and vaaya.agents.list() both list agents. An omitted update field stays unchanged; ceiling_cents=None explicitly removes a ceiling. wallet() and transactions() return balances and receipts.

LangChain

Install the optional dependency with pip install "vaaya[langchain]" after the registry release, or install langchain-core alongside the local wheel.

from vaaya import langchain_tools

tools = langchain_tools(vaaya)
# Pass these runnable StructuredTools to your LangChain agent.
search = next(tool for tool in tools if tool.name == "vaaya_search")
result = search.invoke({"query": "battery recycling"})

openai_tools(vaaya), responses_tools(vaaya), and anthropic_tools(vaaya) each return {"tools": [...], "handle": callable} for custom tool loops. Chat Completions and Responses use separate definition shapes.

LLMs and paid URLs

vaaya.llm.chat(messages) returns a non-streaming completion using the auto model. For streaming, configure an OpenAI client with vaaya.llm.base_url and vaaya.llm.api_key.

vaaya.fetch(url, max_cost_cents=10) pays x402/MPP URLs through Vaaya. This requires the server's PAID_FETCH_ENABLED flag; the ceiling is mandatory.

Errors and configuration

Every API failure raises VaayaError with code, status, message, and the original body. Spend-gate errors expose is_spend_gate, card_url, and credits_url. Transport failures do not prove that a paid request failed: reuse its idempotency key when retrying. The SDK does not retry paid requests automatically.

Constructor options: api_key, base_url, agent_tag, timeout (seconds, default 300), and an injectable transport for tests.