Skip to main content

BlockRun LLM SDK

Pay-per-request access to GPT-4o, Claude 4, Gemini 2.5, and more via x402 micropayments on Base.

BlockRun assumes Claude Code as the agent runtime.

Network: Base (Chain ID: 8453) Payment: USDC Protocol: x402 v2 (CDP Facilitator)

Installation

pip install blockrun-llm

Quick Start

from blockrun_llm import LLMClient

client = LLMClient()  # Uses BLOCKRUN_WALLET_KEY (never sent to server)
response = client.chat("openai/gpt-4o", "Hello!")

That's it. The SDK handles x402 payment automatically.

How It Works

  1. You send a request to BlockRun's API
  2. The API returns a 402 Payment Required with the price
  3. The SDK automatically signs a USDC payment on Base
  4. The request is retried with the payment proof
  5. You receive the AI response

Your private key never leaves your machine - it's only used for local signing.

Available Models

OpenAI GPT-5 Family

Model Input Price Output Price
openai/gpt-5.2 $1.75/M $14.00/M
openai/gpt-5-mini $0.25/M $2.00/M
openai/gpt-5-nano $0.05/M $0.40/M
openai/gpt-5.2-pro $21.00/M $168.00/M

OpenAI GPT-4 Family

Model Input Price Output Price
openai/gpt-4.1 $2.00/M $8.00/M
openai/gpt-4.1-mini $0.40/M $1.60/M
openai/gpt-4.1-nano $0.10/M $0.40/M
openai/gpt-4o $2.50/M $10.00/M
openai/gpt-4o-mini $0.15/M $0.60/M

OpenAI O-Series (Reasoning)

Model Input Price Output Price
openai/o1 $15.00/M $60.00/M
openai/o1-mini $1.10/M $4.40/M
openai/o3 $2.00/M $8.00/M
openai/o3-mini $1.10/M $4.40/M
openai/o4-mini $1.10/M $4.40/M

OpenAI Open-Source (Apache 2.0)

Model Input Price Output Price
openai/gpt-oss-20b $0.03/M $0.14/M
openai/gpt-oss-120b $0.18/M $0.84/M

Anthropic Claude

Model Input Price Output Price
anthropic/claude-opus-4 $15.00/M $75.00/M
anthropic/claude-sonnet-4 $3.00/M $15.00/M
anthropic/claude-haiku-4.5 $1.00/M $5.00/M

Google Gemini

Model Input Price Output Price
google/gemini-3-pro-preview $2.00/M $12.00/M
google/gemini-2.5-pro $1.25/M $10.00/M
google/gemini-2.5-flash $0.15/M $0.60/M

DeepSeek

Model Input Price Output Price
deepseek/deepseek-chat $0.28/M $0.42/M
deepseek/deepseek-reasoner $0.28/M $0.42/M

Qwen (Alibaba)

Model Input Price Output Price
qwen/qwen3-max $0.46/M $1.84/M
qwen/qwen-plus $0.10/M $0.30/M
qwen/qwen-turbo $0.02/M $0.06/M

xAI Grok

Model Input Price Output Price
xai/grok-3 $3.00/M $15.00/M
xai/grok-3-fast $5.00/M $25.00/M
xai/grok-3-mini $0.30/M $0.50/M

Image Generation

Model Price
openai/dall-e-3 $0.04-0.08/image
openai/gpt-image-1 $0.02-0.04/image
google/nano-banana $0.05/image
google/nano-banana-pro $0.10-0.15/image

Usage Examples

Simple Chat

from blockrun_llm import LLMClient

client = LLMClient()  # Uses BLOCKRUN_WALLET_KEY (never sent to server)

response = client.chat("openai/gpt-4o", "Explain quantum computing")
print(response)

# With system prompt
response = client.chat(
    "anthropic/claude-sonnet-4",
    "Write a haiku",
    system="You are a creative poet."
)
from blockrun_llm import LLMClient

client = LLMClient()

# Simple: Enable live search with search=True (default 10 sources, ~$0.26)
response = client.chat(
    "xai/grok-3",
    "What are the latest posts from @blockrunai?",
    search=True
)
print(response)

# Custom: Limit sources to reduce cost (5 sources, ~$0.13)
response = client.chat(
    "xai/grok-3",
    "What's trending on X?",
    search_parameters={"mode": "on", "max_search_results": 5}
)

Check Spending

from blockrun_llm import LLMClient

client = LLMClient()

response = client.chat("openai/gpt-4o", "Explain quantum computing")
print(response)

# Check how much was spent
spending = client.get_spending()
print(f"Spent ${spending['total_usd']:.4f} across {spending['calls']} calls")

Full Chat Completion

from blockrun_llm import LLMClient

client = LLMClient()  # Uses BLOCKRUN_WALLET_KEY (never sent to server)

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "How do I read a file in Python?"}
]

result = client.chat_completion("openai/gpt-4o", messages)
print(result.choices[0].message.content)

Async Usage

import asyncio
from blockrun_llm import AsyncLLMClient

async def main():
    async with AsyncLLMClient() as client:
        # Simple chat
        response = await client.chat("openai/gpt-4o", "Hello!")
        print(response)

        # Multiple requests concurrently
        tasks = [
            client.chat("openai/gpt-4o", "What is 2+2?"),
            client.chat("anthropic/claude-sonnet-4", "What is 3+3?"),
            client.chat("google/gemini-2.5-flash", "What is 4+4?"),
        ]
        responses = await asyncio.gather(*tasks)
        for r in responses:
            print(r)

asyncio.run(main())

List Available Models

from blockrun_llm import LLMClient

client = LLMClient()
models = client.list_models()

for model in models:
    print(f"{model['id']}: ${model['inputPrice']}/M input, ${model['outputPrice']}/M output")

Environment Variables

Variable Description Required
BLOCKRUN_WALLET_KEY Your Base chain wallet private key Yes (or pass to constructor)
BLOCKRUN_API_URL API endpoint No (default: https://blockrun.ai/api)

Setting Up Your Wallet

  1. Create a wallet on Base network (Coinbase Wallet, MetaMask, etc.)
  2. Get some ETH on Base for gas (small amount, ~$1)
  3. Get USDC on Base for API payments
  4. Export your private key and set it as BLOCKRUN_WALLET_KEY
# .env file
BLOCKRUN_WALLET_KEY=0x...your_private_key_here

Error Handling

from blockrun_llm import LLMClient, APIError, PaymentError

client = LLMClient()

try:
    response = client.chat("openai/gpt-4o", "Hello!")
except PaymentError as e:
    print(f"Payment failed: {e}")
    # Check your USDC balance
except APIError as e:
    print(f"API error ({e.status_code}): {e}")

Testing

Running Unit Tests

Unit tests do not require API access or funded wallets:

pytest tests/unit                    # Run unit tests only
pytest tests/unit --cov              # Run with coverage report
pytest tests/unit -v                 # Verbose output

Running Integration Tests

Integration tests call the production API and require:

  • A funded Base wallet with USDC ($1+ recommended)
  • BLOCKRUN_WALLET_KEY environment variable set
  • Estimated cost: ~$0.05 per test run
export BLOCKRUN_WALLET_KEY=0x...
pytest tests/integration             # Run integration tests only
pytest                               # Run all tests

Integration tests are automatically skipped if BLOCKRUN_WALLET_KEY is not set.

Security

Private Key Safety

  • Private key stays local: Your key is only used for signing on your machine
  • No custody: BlockRun never holds your funds
  • Verify transactions: All payments are on-chain and verifiable

Best Practices

Private Key Management:

  • Use environment variables, never hard-code keys
  • Use dedicated wallets for API payments (separate from main holdings)
  • Set spending limits by only funding payment wallets with small amounts
  • Never commit .env files to version control
  • Rotate keys periodically

Input Validation: The SDK validates all inputs before API requests:

  • Private keys (format, length, valid hex)
  • API URLs (HTTPS required for production, HTTP allowed for localhost)
  • Model names and parameters (ranges for max_tokens, temperature, top_p)

Error Sanitization: API errors are automatically sanitized to prevent sensitive information leaks.

Monitoring:

address = client.get_wallet_address()
print(f"View transactions: https://basescan.org/address/{address}")

Keep Updated:

pip install --upgrade blockrun-llm  # Get security patches

License

MIT

Metadata

Release files for blockrun-llm 0.3.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for blockrun-llm 0.3.3
File Size Uploaded Provenance Actions
blockrun_llm-0.3.3.tar.gz 33.2 kB Without provenance Details for blockrun_llm-0.3.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for blockrun-llm 0.3.3
File Interpreter ABI Platform Actions
blockrun_llm-0.3.3-py3-none-any.whl Python 3 none any Details for blockrun_llm-0.3.3-py3-none-any.whl

Total release size: 59.8 kB

Release files / blockrun_llm-0.3.3.tar.gz

Download URL blockrun_llm-0.3.3.tar.gz
Size 33.2 kB
Tags Source
SHA-256 checksum
How to use checksums
ee865c752ce785cdc73ff6c980f2b8d09508a1cbac206c0f5029007e2b7f2d2b
BLAKE2b-256 checksum
How to use checksums
718eb8abb83d5e49770f9341ca498a37c828f5bf28a7a06d10f238d3f7452279
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.7

Release files / blockrun_llm-0.3.3-py3-none-any.whl

Download URL blockrun_llm-0.3.3-py3-none-any.whl
Size 26.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b05e84808e266313f6845517639eaee4443de280ff1a435d7f20eeab4b970bc4
BLAKE2b-256 checksum
How to use checksums
e77e4edc076d71792f779284ab9a82d537d61afaac9a8d83f39dc1b1927132f6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.7

Security for blockrun-llm 0.3.3

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.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page