feat(apikey): a BlockRun API key works everywhere a wallet key does

[VickyXAI]

What

The SDK accepts a brk_live_… key from user.blockrun.ai anywhere it accepts a wallet private key. Requests go to api.blockrun.ai, authenticate with Authorization: Bearer …, and draw prepaid credit instead of signing an on-chain payment.

No new client type and no new constructor. The private_key parameter that all fourteen client classes already take now recognises a brk_ prefix, and BLOCKRUN_API_KEY is read when it is empty — so every existing skill and script gains the rail without a code change.

blockrun_llm/apikey.py holds the rail in one module: precedence, auth_headers, poll-URL resolution, and the two refusals. Each client's httpx.Client carries the key as a default header, which is why sixteen request sites did not have to be edited one by one.

Why it needed more than a header

Each of these fails silently rather than at import time:

api.blockrun.ai serves /v1/… at the root and answers /api/v1/… with wrong_host	the account rail needs its own base URL
poll_url is minted relative to the x402 gateway's host, so it arrives as /api/v1/…	resolved unchanged, every async job (video, slow images) polls a 404 until its budget runs out
the async submit answers 202 on the first POST here	ImageClient raised API error: 202, VideoClient raised "Expected 402 on first POST" — both broken for keys before they started
setup_agent_wallet() minted a keyfile unconditionally	with a key configured there is nothing to sign with, so it now writes nothing to disk

SolanaLLMClient / AsyncSolanaLLMClient take the key too, and no longer require the optional x402 SDK when one is present: on the account rail there is no transfer to sign.

Wallet users

Unaffected, and verified live after the change:

LLMClient  mode=wallet  addr=0xCC8c…65EF8  balance=$33.7603  free chat ok

Precedence: an explicit argument, then BLOCKRUN_API_KEY, then the wallet variables. Nothing changes until that variable is set, and passing a wallet key explicitly always opts back out. client.payment_mode makes the choice inspectable.

BLOCKRUN_API_KEY_URL is deliberately not BLOCKRUN_API_URL — the latter names an x402 gateway, and an API-key client following it would send the key to a host configured for a different rail.

Wallet-only helpers

get_balance(), get_balance_testnet() and onramp() raise a ValueError naming the helper and pointing at the dashboard. Returning 0 would be the worst available answer: indistinguishable from an empty wallet, and an agent gating on it would stop calling a well-funded account. get_wallet_address() returns "". A 402 on this rail is a credit refusal, not a challenge, so it raises a PaymentError quoting the gateway's reason and the top-up page.

Every client also raised its own "nothing configured" wording listing only wallet routes, which stopped being the whole truth the moment a key became a credential. missing_credential_error() lists both — the two tests asserting the old wording are updated.

Tests

30 new tests in tests/unit/test_apikey.py; 699 passed, 15 skipped, ruff and black clean.

tests/conftest.py clears BLOCKRUN_API_KEY for every test. Without it, every "no credential configured" test fails on the machine of anyone who actually has a key exported — which is everyone working on this.

Verified live against the real gateway with a real key: chat (paid + free), list_models, list_image_models, Grok Live Search, Exa, RPC, and the wallet-only refusals.

README

Opened with "No API keys required", which is no longer true. Now leads with the two rails, adds the API-key path to Quick Start and a full Option A section (signup, key minting, top-up — min $5, with the 5.5% + $0.30 fee charged once at purchase rather than per call — precedence, and what changes). Solana now leads where the two chains are named: sub-second settlement with the facilitator paying the fee makes it the better default; Base is unchanged and still what the bare LLMClient uses. The environment table listed two variables and omitted SOLANA_WALLET_KEY entirely; it now lists nine.

🤖 Generated with Claude Code

https://claude.ai/code/session_01T5RKUETYjxwNRqkURLnatJ