Skip to content

wallet-setup.md

Latest commit

 

History

History
235 lines (163 loc) · 6 KB

wallet-setup.md

File metadata and controls

235 lines (163 loc) · 6 KB
Raw
title Wallet Setup
description Create and fund a BlockRun wallet with USDC on Base or Solana, manage keys and budgets, and run on testnet — your private key never leaves your machine.

Wallet Setup

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

Networks

Network Chain ID Usage USDC
Base Mainnet 8453 Production (default) Real USDC
Base Sepolia 84532 Development/Testing Testnet USDC (free)
Solana Mainnet — Production USDC (SPL)

:::info{title="MCP users: pay on Solana"} Switch to Solana with blockrun_wallet action:"chain" chain:"solana" then blockrun_wallet action:"setup" — no env vars or restart. See Claude Code MCP. Some tools (image, music, speech, video, paid stock prices, smart routing, native Anthropic) settle on Base only. :::

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:

blockrun setup

Python SDK:

from blockrun_llm import LLMClient

client = LLMClient()  # Creates wallet at ~/.blockrun/wallet.json if none exists
print(client.get_address())

TypeScript SDK:

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

const client = new LLMClient();  // Creates wallet if none exists
console.log(await client.getAddress());

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...")

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

Method Best For
Coinbase Direct withdrawal to Base
Base Bridge Bridge from Ethereum mainnet
Uniswap Swap ETH for USDC on Base
Relay Cross-chain bridge

Recommended Amounts

Usage Amount
Testing $1-5
Regular usage $5-20
Heavy usage / Trading $20-100

Check Balance

Claude Code:

blockrun balance

Python:

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

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

Platform Location
Claude Code / MCP ~/.blockrun/wallet.json
Python SDK ~/.blockrun/wallet.json or env var
TypeScript SDK ~/.blockrun/wallet.json or env var

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

:::danger Never commit your private key or paste it into a shared chat. Anyone with the key controls the wallet and its funds. :::

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:

::::steps

:::step{title="Get testnet ETH"} Get free testnet ETH for gas from Alchemy Base Sepolia Faucet. :::

:::step{title="Get testnet USDC"} Get free testnet USDC from Circle USDC Faucet. :::

:::step{title="Configure the SDK for testnet"} Python:

from blockrun_llm import testnet_client

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

TypeScript:

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.003/request
  • openai/gpt-oss-120b - $0.004/request

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

"Wallet not found"

# Check if wallet file exists
ls ~/.blockrun/

# Create new wallet
blockrun setup

What's next?

::::cards

:::card{title="Claude Code guide" href="claude-code.md" icon="Terminal"} Install the MCP and use your funded wallet from Claude Code. :::

:::card{title="SDK developers" href="sdk-developers.md" icon="Code"} Wire the wallet into Python, TypeScript, or Go integrations. :::

:::card{title="Agent developers" href="agent-developers.md" icon="Boxes"} Give agents a wallet that pays for their own intelligence. :::

::::