mirror of
https://github.com/NoFxAiOS/nofx.git
synced 2026-06-06 05:51:19 +08:00
feat: add BlockRun wallet provider for pay-per-request AI access (#1408)
Integrates BlockRun (blockrun.ai) as a new AI provider option via x402 micropayment protocol, allowing users to access top AI models with USDC without requiring individual API keys. - Add BlockRun Base (EVM) and Solana wallet providers to model selector - Implement x402 v2 EIP-712 payment signing for Base (mcp/blockrun_base.go) - Implement x402 v2 SPL TransferChecked signing for Solana (mcp/blockrun_sol.go) - Wire blockrun-base and blockrun-sol into trader factory (auto_trader.go) - Register both providers in supported models API (server.go) - Add BlockRun card UI with wallet key input in Step 0/1 of model config modal - Add BlockRun SVG icon and ModelIcons support - Add setup guides for Base and Solana wallet configuration (docs/) - Available flagship models: GPT-5.4, Claude Opus 4.6, Gemini 3.1 Pro, Grok 3, DeepSeek Chat, MiniMax M2.5
This commit is contained in:
1bcMax
@@ -44,6 +44,19 @@ Use custom AI models or third-party OpenAI-compatible APIs:
|
||||
|
||||
---
|
||||
|
||||
### 💳 BlockRun Wallet (Pay-per-Request, No API Key)
|
||||
|
||||
Access all top AI models by paying with USDC — no API key signup required.
|
||||
|
||||
| Provider | Guide | Payment Network |
|
||||
|----------|-------|-----------------|
|
||||
| BlockRun (Base Wallet) | [blockrun-base-wallet.md](blockrun-base-wallet.md) | Base (EVM) · USDC |
|
||||
| BlockRun (Solana Wallet) | [blockrun-sol-wallet.md](blockrun-sol-wallet.md) | Solana · USDC |
|
||||
|
||||
**How it works:** Each AI request automatically pays a micro-USDC fee via the [x402 payment protocol](https://blockrun.ai). Your private key signs the payment authorization — no funds leave your wallet until the AI response is delivered.
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Prerequisites
|
||||
|
||||
Before starting, ensure you have:
|
||||
|
||||
126
docs/getting-started/blockrun-base-wallet.md
Normal file
126
docs/getting-started/blockrun-base-wallet.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# BlockRun Base (EVM) Wallet Setup Guide
|
||||
|
||||
This guide explains how to use a Base network EVM wallet to pay for AI usage through BlockRun — no API key required.
|
||||
|
||||
**Language:** [English](blockrun-base-wallet.md) | [中文](blockrun-base-wallet.zh-CN.md)
|
||||
|
||||
## What is BlockRun?
|
||||
|
||||
[BlockRun](https://blockrun.ai) is a decentralized AI inference gateway that lets you access top AI models (Claude, GPT, Gemini, Grok, DeepSeek, etc.) by paying per request with USDC — no monthly subscriptions, no API key signups.
|
||||
|
||||
NOFX integrates BlockRun via the **x402 micropayment protocol**: each AI inference request automatically pays a small USDC fee directly from your wallet. You only pay for what you use.
|
||||
|
||||
## Why Use BlockRun?
|
||||
|
||||
| Feature | Traditional API Key | BlockRun Wallet |
|
||||
|---------|-------------------|-----------------|
|
||||
| Setup | Register + billing | Just a wallet address |
|
||||
| Cost model | Monthly subscription | Pay-per-request |
|
||||
| Models | One provider | All top models |
|
||||
| Privacy | Account required | Pseudonymous |
|
||||
| Control | Rate limits apply | Your wallet, your budget |
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- An EVM wallet with USDC on **Base network** (chain ID 8453)
|
||||
- The wallet private key (hex format: `0x...`)
|
||||
|
||||
### Getting USDC on Base
|
||||
|
||||
1. Buy USDC on Coinbase and withdraw to Base, **or**
|
||||
2. Bridge USDC from Ethereum using [bridge.base.org](https://bridge.base.org), **or**
|
||||
3. Swap on [Aerodrome](https://aerodrome.finance) or [Uniswap](https://app.uniswap.org) on Base
|
||||
|
||||
> **Tip:** A few dollars of USDC is enough to start — each AI call costs fractions of a cent.
|
||||
|
||||
## Step 1: Get Your Wallet Private Key
|
||||
|
||||
> ⚠️ **Security Warning:** Never share your private key with anyone. Use a dedicated trading wallet, not your main holdings wallet.
|
||||
|
||||
**Option A — Create a new wallet (recommended):**
|
||||
1. Open MetaMask → Create New Account
|
||||
2. Go to Account Details → Export Private Key
|
||||
3. Copy the hex key (starts with `0x`)
|
||||
|
||||
**Option B — Use an existing wallet:**
|
||||
1. MetaMask → Account Details → Export Private Key
|
||||
2. Enter your MetaMask password to reveal the key
|
||||
|
||||
**Option C — Generate via CLI:**
|
||||
```bash
|
||||
# Using cast (foundry)
|
||||
cast wallet new
|
||||
# Output: Address: 0x... | Private key: 0x...
|
||||
```
|
||||
|
||||
## Step 2: Fund the Wallet with USDC on Base
|
||||
|
||||
Send USDC to your wallet address on Base network:
|
||||
- **USDC contract:** `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
|
||||
- **Network:** Base (chain ID 8453)
|
||||
- **Recommended starting amount:** $5–$20 USDC
|
||||
|
||||
Check your balance at [basescan.org](https://basescan.org).
|
||||
|
||||
## Step 3: Configure in NOFX
|
||||
|
||||
1. Open NOFX at `http://localhost:3000`
|
||||
2. Log in and go to **Config** tab
|
||||
3. Click **+ Add AI Model**
|
||||
4. In Step 0, scroll to **Via BlockRun Wallet** section
|
||||
5. Select **BlockRun · Base Wallet**
|
||||
6. In Step 1, configure:
|
||||
- **Wallet Private Key:** Your hex private key (`0x...`)
|
||||
- **Select Model:** Choose from Claude Opus, GPT-5.4, Gemini 3 Pro, Grok 3, DeepSeek R1, or leave as **Auto** for best available
|
||||
7. Click **Save**
|
||||
|
||||
## How Payment Works
|
||||
|
||||
When NOFX sends an AI request:
|
||||
|
||||
1. Request goes to `https://blockrun.ai/api/v1/chat/completions`
|
||||
2. Server responds with HTTP `402 Payment Required` + payment details
|
||||
3. NOFX signs a **ERC-3009 TransferWithAuthorization** (EIP-712) with your private key
|
||||
4. Payment signature is attached and request is retried
|
||||
5. BlockRun verifies the signature, routes the request to the AI model, and charges USDC
|
||||
|
||||
> **Privacy:** Your private key never leaves your NOFX instance. Only the cryptographic signature is sent.
|
||||
|
||||
## Available Models via BlockRun
|
||||
|
||||
| Model ID | Provider | Use Case |
|
||||
|----------|----------|----------|
|
||||
| `gpt-5.4` | OpenAI | Flagship (default) |
|
||||
| `claude-opus-4.6` | Anthropic | Flagship |
|
||||
| `gemini-3.1-pro` | Google | Flagship |
|
||||
| `grok-3` | xAI | Flagship |
|
||||
| `deepseek-chat` | DeepSeek | Flagship |
|
||||
| `minimax-m2.5` | MiniMax | Flagship |
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
- ✅ Use a **dedicated wallet** with only trading budget, not your main wallet
|
||||
- ✅ Keep only a small USDC balance (top up as needed)
|
||||
- ✅ Your private key is encrypted at rest in NOFX's database
|
||||
- ✅ Signatures are spend-limited — each signature authorizes only the exact amount for one request
|
||||
- ❌ Never export or share your private key outside of NOFX
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| `no private key set` | Check your key was saved correctly; re-enter in Config |
|
||||
| `payment retry failed` | Ensure you have USDC on **Base** (not Ethereum mainnet) |
|
||||
| `invalid private key` | Key must be hex format with `0x` prefix, 66 chars total |
|
||||
| Payment deducted but no response | Check BlockRun status at [blockrun.ai](https://blockrun.ai) |
|
||||
| Slow responses | Try selecting a specific model instead of "Auto" |
|
||||
|
||||
## Monitoring Spend
|
||||
|
||||
Check your USDC balance and transaction history at:
|
||||
- [Basescan](https://basescan.org) — search your wallet address
|
||||
- [BlockRun dashboard](https://blockrun.ai) — usage history
|
||||
|
||||
---
|
||||
|
||||
[← Back to Getting Started](README.md)
|
||||
120
docs/getting-started/blockrun-sol-wallet.md
Normal file
120
docs/getting-started/blockrun-sol-wallet.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# BlockRun Solana Wallet Setup Guide
|
||||
|
||||
This guide explains how to use a Solana wallet to pay for AI usage through BlockRun — no API key required.
|
||||
|
||||
**Language:** [English](blockrun-sol-wallet.md) | [中文](blockrun-sol-wallet.zh-CN.md)
|
||||
|
||||
## What is BlockRun?
|
||||
|
||||
[BlockRun](https://blockrun.ai) is a decentralized AI inference gateway that lets you access top AI models (Claude, GPT, Gemini, Grok, DeepSeek, etc.) by paying per request with USDC — no monthly subscriptions, no API key signups.
|
||||
|
||||
NOFX integrates BlockRun via the **x402 micropayment protocol** on Solana: each AI inference request automatically pays a small USDC fee directly from your wallet.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A Solana wallet with USDC on **Solana mainnet**
|
||||
- The wallet private key (base58-encoded, 64 bytes — standard Solana keypair format)
|
||||
|
||||
### Getting USDC on Solana
|
||||
|
||||
1. Buy SOL on any exchange and withdraw to your Solana wallet, then swap to USDC on [Jupiter](https://jup.ag), **or**
|
||||
2. Buy USDC directly on an exchange and withdraw to Solana, **or**
|
||||
3. Bridge from other chains using [Wormhole](https://wormhole.com)
|
||||
|
||||
> **Tip:** A few dollars of USDC is plenty to start.
|
||||
|
||||
## Step 1: Export Your Solana Private Key
|
||||
|
||||
> ⚠️ **Security Warning:** Use a dedicated wallet for NOFX — not your main holdings wallet.
|
||||
|
||||
**From Phantom Wallet:**
|
||||
1. Open Phantom → Settings (gear icon)
|
||||
2. Security & Privacy → Export Private Key
|
||||
3. Enter your password
|
||||
4. Copy the base58 key (looks like: `5J...` — a long string of ~88 characters)
|
||||
|
||||
**From Solflare:**
|
||||
1. Settings → Export Private Key
|
||||
2. The key is displayed in base58 format
|
||||
|
||||
**From CLI (solana-keygen):**
|
||||
```bash
|
||||
# View existing keypair
|
||||
cat ~/.config/solana/id.json
|
||||
# This is a JSON array — convert to base58 using:
|
||||
solana-keygen pubkey ~/.config/solana/id.json
|
||||
```
|
||||
|
||||
> **Note:** NOFX accepts the **base58-encoded 64-byte keypair** (as exported by Phantom/Solflare). This is the standard format for Solana private keys.
|
||||
|
||||
## Step 2: Fund the Wallet with USDC on Solana
|
||||
|
||||
Send USDC to your Solana wallet:
|
||||
- **USDC SPL token mint:** `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`
|
||||
- **Network:** Solana Mainnet
|
||||
- **Recommended starting amount:** $5–$20 USDC
|
||||
|
||||
Check your balance at [solscan.io](https://solscan.io) or in your wallet app.
|
||||
|
||||
## Step 3: Configure in NOFX
|
||||
|
||||
1. Open NOFX at `http://localhost:3000`
|
||||
2. Log in and go to **Config** tab
|
||||
3. Click **+ Add AI Model**
|
||||
4. In Step 0, scroll to **Via BlockRun Wallet** section
|
||||
5. Select **BlockRun · Solana Wallet**
|
||||
6. In Step 1, configure:
|
||||
- **Wallet Private Key:** Your base58-encoded Solana private key
|
||||
- **Select Model:** Choose from Claude Opus, GPT-5.4, Gemini 3 Pro, Grok 3, DeepSeek R1, or leave as **Auto** for best available
|
||||
7. Click **Save**
|
||||
|
||||
## How Payment Works
|
||||
|
||||
When NOFX sends an AI request:
|
||||
|
||||
1. Request goes to `https://sol.blockrun.ai/api/v1/chat/completions`
|
||||
2. Server responds with HTTP `402 Payment Required` + payment details (nonce, recipient, amount)
|
||||
3. NOFX signs the payment message `blockrun-payment:{nonce}:{recipient}:{amount}` with your **Ed25519** private key
|
||||
4. Payment signature is attached and request is retried
|
||||
5. BlockRun verifies the Ed25519 signature on-chain and routes to the AI model
|
||||
|
||||
> **Privacy:** Your private key never leaves your NOFX instance. Only the cryptographic signature is sent.
|
||||
|
||||
## Available Models via BlockRun
|
||||
|
||||
| Model ID | Provider | Use Case |
|
||||
|----------|----------|----------|
|
||||
| `gpt-5.4` | OpenAI | Flagship (default) |
|
||||
| `claude-opus-4.6` | Anthropic | Flagship |
|
||||
| `gemini-3.1-pro` | Google | Flagship |
|
||||
| `grok-3` | xAI | Flagship |
|
||||
| `deepseek-chat` | DeepSeek | Flagship |
|
||||
| `minimax-m2.5` | MiniMax | Flagship |
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
- ✅ Use a **dedicated trading wallet** with only your AI budget
|
||||
- ✅ Keep only a small USDC balance (top up as needed)
|
||||
- ✅ Your private key is AES-256 encrypted at rest in NOFX's database
|
||||
- ✅ Ed25519 signatures are one-time — each authorizes only one specific payment
|
||||
- ❌ Never use your main SOL holdings wallet as the NOFX trading wallet
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| `unexpected key length` | Ensure you exported the full 64-byte keypair (not just the 32-byte seed) |
|
||||
| `failed to decode base58` | Key must be base58 encoded (standard Phantom/Solflare export format) |
|
||||
| `payment retry failed` | Ensure you have USDC on **Solana mainnet** (not devnet) |
|
||||
| No response from server | Check `sol.blockrun.ai` is reachable from your server |
|
||||
| Slow responses | Try selecting a specific model instead of "Auto" |
|
||||
|
||||
## Monitoring Spend
|
||||
|
||||
Check your USDC balance and transaction history at:
|
||||
- [Solscan](https://solscan.io) — search your wallet address, filter by USDC token
|
||||
- [BlockRun dashboard](https://blockrun.ai) — usage history
|
||||
|
||||
---
|
||||
|
||||
[← Back to Getting Started](README.md)
|
||||
Reference in New Issue
Block a user