invinoveritas 0.3.1

Lightning-paid reasoning and decision intelligence for autonomous agents

invinoveritas SDK

Lightning-paid reasoning and decision intelligence for autonomous agents.

Pay per insight. No subscriptions. No accounts. No KYC.
Atomic intelligence purchases over Bitcoin Lightning using the L402 protocol. ⚡

---

Installation

# Core (sync client)
pip install invinoveritas

# With async support (recommended for agents)
pip install "invinoveritas[async]"

# With LangChain autonomous payment handler
pip install "invinoveritas[langchain]"

---

What's new in v0.2.0

Autonomous LangChain payments. Agents can now call invinoveritas tools with zero human intervention — the InvinoCallbackHandler intercepts tool calls, pays Lightning invoices automatically via your LND node, and retries. The agent never sees the payment.

from invinoveritas.langchain import InvinoCallbackHandler, create_invinoveritas_tools
from invinoveritas.providers import LNDProvider

handler = InvinoCallbackHandler(
    provider=LNDProvider(
        macaroon_path="/root/.lnd/data/chain/bitcoin/mainnet/admin.macaroon",
        cert_path="/root/.lnd/tls.cert"
    )
)

tools = create_invinoveritas_tools(handler)
result = agent.run("Should I increase my BTC exposure in 2026?", callbacks=[handler])

---

Quickstart

Sync (manual payment flow)

from invinoveritas import InvinoClient, PaymentRequired

client = InvinoClient()

try:
    result = client.reason("What are the biggest risks for Bitcoin in 2026?")
except PaymentRequired as e:
    print(f"Pay this invoice → {e.invoice}")
    print(f"Amount: {e.amount_sats} sats")

    result = client.reason(
        "What are the biggest risks for Bitcoin in 2026?",
        payment_hash=e.payment_hash,
        preimage="preimage_from_wallet_here",
    )

print(result.answer)

Async

import asyncio
from invinoveritas import AsyncInvinoClient, PaymentRequired

async def main():
    async with AsyncInvinoClient() as client:
        try:
            result = await client.reason("What are the biggest risks for Bitcoin in 2026?")
        except PaymentRequired as e:
            result = await client.reason(
                "What are the biggest risks for Bitcoin in 2026?",
                payment_hash=e.payment_hash,
                preimage="preimage_from_wallet_here",
            )
            print(result.answer)

asyncio.run(main())

---

Core Tools

reason() — Deep strategic reasoning

result = client.reason(
    question="Should we expand into the European market in 2026?",
    payment_hash=...,
    preimage=...
)
print(result.answer)

Base price: ~500 sats

---

decide() — Structured decision intelligence

result = client.decide(
    goal="Grow capital safely while managing risk",
    question="Should I increase BTC exposure now?",
    context="Portfolio is 60% BTC, 30% stablecoins, 10% cash",
    payment_hash=...,
    preimage=...
)

print(result.decision)    # "Increase BTC exposure slightly"
print(result.confidence)  # 0.78
print(result.reasoning)
print(result.risk_level)  # "low" | "medium" | "high"

Base price: ~1000 sats

---

Autonomous Agent Integration (v0.2.0)

LangChain — fully autonomous payments

pip install "invinoveritas[langchain]"

from invinoveritas.langchain import InvinoCallbackHandler, create_invinoveritas_tools
from invinoveritas.providers import LNDProvider
from langchain.agents import initialize_agent

handler = InvinoCallbackHandler(
    provider=LNDProvider(
        macaroon_path="/root/.lnd/data/chain/bitcoin/mainnet/admin.macaroon",
        cert_path="/root/.lnd/tls.cert"
    ),
    budget_sats=10000  # optional spend cap per run
)

tools = create_invinoveritas_tools(handler)
agent = initialize_agent(tools=tools, ...)
result = agent.run("Should I increase my BTC exposure in 2026?")
print(f"Total spent: {handler.total_spent_sats} sats")

AutoGen

from invinoveritas.langchain import InvinoAutoGenTool
from invinoveritas.providers import LNDProvider

tool = InvinoAutoGenTool(
    provider=LNDProvider(
        macaroon_path="/root/.lnd/...",
        cert_path="/root/.lnd/tls.cert"
    )
)

result = await tool.reason("What are Bitcoin's biggest risks in 2026?")
result = await tool.decide(
    goal="Grow capital safely",
    question="Should I increase BTC exposure?"
)

Bring your own wallet

async def my_pay(invoice: str) -> str:
    result = await my_wallet.pay(invoice)
    return result.preimage

handler = InvinoCallbackHandler(pay_invoice=my_pay)

lnget (CLI agents)

lnget handles L402 automatically at the CLI level:

lnget POST https://invinoveritas.onrender.com/reason \
  '{"question": "What are the biggest risks for Bitcoin in 2026?"}'

---

Payment Flow (L402)

1. Call any method → server returns 402 Payment Required + Lightning invoice
2. Pay the invoice using any Lightning wallet
3. Retry the same call with payment_hash and preimage

The SDK handles this automatically in autonomous mode. In manual mode, PaymentRequired carries everything you need.

Each invoice is single-use. Reusing a payment hash returns PaymentError.

---

Providers (v0.2.0)

Provider	Install	Description
LNDProvider	built-in	Pay via local LND node using lncli
NWCProvider	invinoveritas[nwc]	Nostr Wallet Connect (v0.3.0)
CustomProvider	built-in	Bring any async pay function

---

Exceptions

Exception	Trigger	Attributes
PaymentRequired	402 — no valid payment	.invoice, .payment_hash, .amount_sats
PaymentError	401/403 — invalid or used payment	—
InvinoError	429 — rate limited	—
ServiceError	5xx or malformed response	—

All exceptions inherit from InvinoError.

---

Utility Methods

client = InvinoClient()

health = client.check_health()      # full health + pricing dict
price  = client.get_price("reason") # int sats

---

MCP Support

Connect directly without the SDK using any MCP-compatible client (Claude Desktop, Cursor):

https://invinoveritas.onrender.com/mcp

Listed on the official MCP Registry: io.github.babyblueviper1/invinoveritas

---

Local Development

client = InvinoClient(base_url="http://localhost:8000")
async with AsyncInvinoClient(base_url="http://localhost:8000") as client:
    ...

---

Links

• Live API: https://invinoveritas.onrender.com
• Health + Pricing: https://invinoveritas.onrender.com/health
• Payment Guide: https://invinoveritas.onrender.com/guide
• MCP Endpoint: https://invinoveritas.onrender.com/mcp
• PyPI: https://pypi.org/project/invinoveritas/
• GitHub: https://github.com/babyblueviper1/invinoveritas

---

License

Apache-2.0