bridgenode-llm

BridgeNode Python SDK — AI inference for AI agents, no API keys. Pay per request with Solana USDC via x402. The payment handshake is fully automatic, and fees are sponsored — the agent needs no SOL.

Features

• Start free, no wallet — free models run without payment, and the first 2 calls to a paid model are free per client (free trials); a wallet is needed only after that
• No API keys, no registration — pay per request with USDC
• Automatic x402 handshake — 402 → signed transaction → 200, fully hidden
• Fee sponsorship (gasless) — the agent needs zero SOL
• Fail-closed spending policy — per-call and daily caps checked before signing
• Receipt verification — every response receipt is verified (invalid → error)
• Smart routing — mode: auto / eco / premium (model selection per prompt complexity)
• MCP support — BridgeNode is also available as an MCP server

BridgeNode vs traditional APIs

Installation

pip install bridgenode-llm

Or install the full toolkit (SDK + CLI):

pip install bridgenode

Usage

from bridgenode_llm import LLMClient

client = LLMClient()  # wallet key from .env (BRIDGENODE_WALLET_KEY) — optional
resp = client.chat("deepseek-flash", [
    {"role": "user", "content": "Hello!"}])
print(resp["choices"][0]["message"]["content"])

Everything is handled automatically: payment, retry, receipt verification. No API key required.

Free path — no wallet needed

Free models ("free": true in GET /v1/models) run without payment, and a client that has never called BridgeNode gets 2 free calls on PAID models (free trials) — real inference before any wallet exists. BRIDGENODE_WALLET_KEY is read lazily: it is required only when a request actually reaches the payment wall, and then the SDK raises one actionable error instead of a broken handshake. The remaining trial count is exposed after every call:

client = LLMClient()          # no wallet required for the free path
resp = client.chat("gpt-oss-120b", [{"role": "user", "content": "hi"}])
print(client.last_trials_remaining)   # None for free models, 1 → 0 for trials

Smart routing

# Let BridgeNode pick the model: auto / eco / premium
resp = client.chat(None, "Explain quantum computing", mode="auto")

Tool calling

Send your own tool definitions (OpenAI format) and run the agent loop yourself — the SDK forwards tools/tool_choice unchanged and returns the provider answer untouched:

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Current weather for a city",
        "parameters": {"type": "object",
                       "properties": {"city": {"type": "string"}},
                       "required": ["city"]},
    },
}]

messages = [{"role": "user", "content": "What is the weather in Vilnius?"}]
while True:
    resp = client.chat("gpt-oss-120b", messages, tools=tools)
    message = resp["choices"][0]["message"]
    messages.append(message)
    if not message.get("tool_calls"):
        print(message["content"])
        break
    for call in message["tool_calls"]:
        # run your own tool here (arguments is a JSON string)
        messages.append({"role": "tool", "tool_call_id": call["id"],
                         "content": '{"temp_c": 7}'})

Notes:

• The tool-calling answer has content: null, finish_reason: "tool_calls" and message.tool_calls — that is normal, not an error.
• Every round is its own paid request (one x402 payment per call).
• The tool schema counts as input tokens: it raises the price, and large tool sets do not fit the free trial budget (8 000 tokens on the free models).
• Only models marked "tools": true in GET /v1/models support this.

Configuration (.env)

# Optional — your Solana wallet private key (base58).
# Needed only for PAID requests: free models and the 2 free trials work without it.
BRIDGENODE_WALLET_KEY=...

# Optional
# BRIDGENODE_BASE_URL=https://bridgenode.cc/v1
# BRIDGENODE_MAX_PER_CALL=0.05   # spending policy: max USD per call (fail-closed)
# BRIDGENODE_DAILY_CAP=1.0       # spending policy: max USD per day

Security

• Receipt verification: after each response, the payment receipt is verified (success, network, payer, signature over your transaction, amount). Invalid receipt → BridgenodeError.
• Spending policy (fail-closed): BRIDGENODE_MAX_PER_CALL + BRIDGENODE_DAILY_CAP are checked BEFORE signing; exceeded → blocked, no payment.
• SIWX: automatic known-agent identification — falls back to payment if auth fails.

Requirements

• Python ≥ 3.11
• A Solana wallet with a USDC token account (ATA) — only for PAID requests; the free path (free models + free trials) needs no wallet

FAQ

Do agents need SOL? No — fees are sponsored. The agent pays only the USDC request amount.

Is there an API key? No. Your wallet signature is the identity (SIWX); payment is the access.

Can an agent try it without a wallet? Yes — free models and the first 2 calls to a paid model per client are free, over HTTP, MCP and both SDKs.

What happens if the spending cap is exceeded? The request is blocked before signing — fail-closed, no payment is made.

Which models are available? See https://bridgenode.cc/v1/models (live list with prices).

How is the payment receipt verified? Every response includes a receipt; the SDK verifies its signature, network, payer and amount — invalid receipts raise BridgenodeError.

Can I use this in CI / headless agents? Yes — no browser, no keys, just a wallet private key in env.

Related packages

The BridgeNode toolkit on PyPI:

• bridgenode-llm — Python SDK (this package): https://pypi.org/project/bridgenode-llm
• bridgenode-cli — command-line interface: https://pypi.org/project/bridgenode-cli
• bridgenode — full toolkit (SDK + CLI): https://pypi.org/project/bridgenode
• bridgenode-sdk — SDK alias package: https://pypi.org/project/bridgenode-sdk
• bridgenode-mcp — MCP server package: https://pypi.org/project/bridgenode-mcp
• bridgenode-skill — agent skill package: https://pypi.org/project/bridgenode-skill

Links

• Website: https://bridgenode.cc
• Models & prices: https://bridgenode.cc/v1/models
• Documentation: https://bridgenode.cc/llms.txt
• Protocol: x402 V2 (https://docs.x402.org)

Community

• Moltbook agent profile: https://moltbook.com/u/bridgenode_eli
• Discord: https://discord.gg/HUpVKxJxhG
• X (Twitter): https://x.com/eliBNx

⭐ Star this repo — it helps AI agents discover BridgeNode.