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
- You send a request to BlockRun's API
- The API returns a 402 Payment Required with the price
- The SDK automatically signs a USDC payment on Base
- The request is retried with the payment proof
- 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."
)
Real-time X/Twitter Search (xAI Live Search)
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
- Create a wallet on Base network (Coinbase Wallet, MetaMask, etc.)
- Get some ETH on Base for gas (small amount, ~$1)
- Get USDC on Base for API payments
- 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_KEYenvironment 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
.envfiles 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
Links
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.