Wallet Setup

BlockRun accepts USDC on Base (default) or Solana for payments. Your agent needs a funded wallet to pay for services.

Networks

How It Works

1. Your agent has a wallet with a private key stored locally
2. When using paid services, the SDK signs a USDC payment authorization
3. The signature (not your key) is sent to the server
4. Payment settles on-chain, you receive the service

Your private key never leaves your machine.

Setup Options

Option 1: Auto-generated Wallet (Recommended)

BlockRun SDKs can generate a wallet automatically:

Claude Code (MCP):

blockrun_wallet action:"setup"

Python SDK:

from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet()  # Creates ~/.blockrun/.session if none exists and prints a funding QR
print(client.get_wallet_address())

LLMClient() on its own does not create a wallet — it raises ValueError if no key is found in the environment or at ~/.blockrun/.session.

TypeScript SDK:

import { setupAgentWallet } from '@blockrun/llm';

const client = setupAgentWallet();  // Creates ~/.blockrun/.session if none exists
console.log(client.getWalletAddress());

Option 2: Use Existing Private Key

If you have an existing wallet, set the environment variable:

export BLOCKRUN_WALLET_KEY=0x...your_private_key...

Or pass it directly:

client = LLMClient(private_key="0x...")

Solana (Python SDK): install the extra and use the Solana client. The key can be a bs58 keypair or seed, the Solana CLI's ~/.config/solana/id.json byte array, or 64-byte hex:

pip install "blockrun-llm[solana]"
export SOLANA_WALLET_KEY=...

from blockrun_llm import SolanaLLMClient, setup_agent_solana_wallet

client = SolanaLLMClient()              # SOLANA_WALLET_KEY, else ~/.blockrun/.solana-session
client = setup_agent_solana_wallet()    # creates ~/.blockrun/.solana-session if none exists

Base and Solana keys are not interchangeable (a Base key is 0x + 64 hex); pass each to its own client. The payer must already hold a USDC token account on Solana.

Adopt a wallet another application created: the SDK never switches wallets on its own. List what it found and import one deliberately — your current key is backed up to ~/.blockrun/.session.backup-<timestamp> first:

from blockrun_llm import list_discovered_wallets, import_wallet

for w in list_discovered_wallets():
    print(w["address"], "from", w["source"])
import_wallet("0x...")

Option 3: BlockRun MCP session wallet

Installing BlockRun MCP auto-creates a wallet at ~/.blockrun/.session on first use — the Python and TypeScript SDKs read the same file automatically, so one funded wallet serves your MCP tools and your scripts:

claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest
# ask the agent for its wallet address, then fund it with USDC on Base

Fund Your Wallet

Get USDC on Base

Recommended Amounts

Check Balance

Claude Code (MCP):

blockrun_wallet action:"status"

Python:

balance = client.get_balance()
print(f"Balance: ${balance} USDC")

# or, one-liner that also creates the wallet if needed:
python3 -c "from blockrun_llm import status; status()"

MCP: ask your agent — the blockrun_wallet tool reports the address and USDC balance.

On-chain:

View your wallet on Basescan by searching your address.

Wallet Location

Every file is written with mode 0600. The MCP and both SDKs share the Base file, so one funded wallet serves all of them.

Spend Limits

The Python SDK can refuse any quote above a ceiling before signing, so an agent can never spend more than you allowed — nothing settles on a refusal:

client = LLMClient(max_cost_per_call=0.25, max_session_cost=10.00)
# or per deployment: BLOCKRUN_MAX_COST_PER_CALL / BLOCKRUN_MAX_SESSION_COST

A refused quote raises SpendLimitError (a PaymentError subclass). Both limits are unset by default.

Security Best Practices

DO:

• Keep your private key secret
• Use a dedicated wallet for BlockRun (not your main holdings)
• Start with small amounts
• Monitor transactions on Basescan

DON'T:

• Share your private key
• Commit your key to git
• Use your main wallet with large holdings
• Ignore transaction failures

Withdraw Funds

Your wallet is a standard Ethereum-compatible wallet. You can withdraw anytime using:

• Any Web3 wallet (MetaMask, Rainbow, etc.)
• Import your private key and send to your desired address

Testnet Setup (Development)

For development and testing, use Base Sepolia testnet with free testnet USDC:

from blockrun_llm import testnet_client

client = testnet_client()  # Uses BLOCKRUN_WALLET_KEY
response = client.chat("openai/gpt-oss-20b", "Hello!")

import { testnetClient } from '@blockrun/llm';

const client = testnetClient({ privateKey: '0x...' });
const response = await client.chat('openai/gpt-oss-20b', 'Hello!');

Testnet API Endpoint

https://testnet.blockrun.ai/api

Available Testnet Models

• openai/gpt-oss-20b - $0.001/request
• openai/gpt-oss-120b - $0.002/request

Testnet also lists the image models and minimax/music-2.5+; see https://testnet.blockrun.ai/api/v1/models.

Troubleshooting

"Insufficient balance"

Check your USDC balance on Base network. ETH for gas is handled by the x402 facilitator — you only need USDC.

"Transaction failed"

1. Verify you have enough USDC for the request
2. Check if the network is congested on Basescan
3. Try again in a few seconds

"No wallet configured"

# Check if the wallet file exists
ls -la ~/.blockrun/.session

# Create a new wallet (Python)
python3 -c "from blockrun_llm import setup_agent_wallet; setup_agent_wallet()"

Or in Claude Code: blockrun_wallet action:"setup". If you hold a Solana key, remember it belongs to SolanaLLMClient, not LLMClient.

What's next?