# Hero Run — LLM / agent setup

Hero Run is one gateway to 375+ AI models (text, image, video, audio) across 10 inference providers. An agent pays in the $HERO token per call. The fees fund open-source AI model training, and each run costs less $HERO over time as funded models get cheaper to run. Base network.

Site: https://hero-run.vercel.app

## Set up the MCP server (for any MCP client, e.g. Claude Code)

1. Download the server:
   curl -o hero-run-mcp.mjs https://hero-run.vercel.app/hero-run-mcp.mjs

2. Install its one dependency:
   npm install viem

3. Get credentials (pick ONE):
   - RECOMMENDED — an API key: mint one at https://hero-run.vercel.app/keys
     (connect a Base wallet, deposit $HERO, receive hr_live_… with prepaid credits). Use it as HERO_RUN_KEY.
   - OR a wallet: a Base wallet private key funded with $HERO + a little ETH. Use it as AGENT_PRIVATE_KEY (pays per call, costs gas).

4. Register it with Claude Code:
   claude mcp add hero-run -e HERO_RUN_KEY=YOUR_KEY -- node /ABSOLUTE/PATH/hero-run-mcp.mjs

   Or add to any MCP client config:
   {
     "mcpServers": {
       "hero-run": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/hero-run-mcp.mjs"],
         "env": { "HERO_RUN_KEY": "YOUR_KEY" }
       }
     }
   }

5. Restart the client. The "hero-run" tools appear.

## Tools

- list_models(kind?)      — list models + $HERO cost (free)
- run_text(prompt, model?)      — run a text model (paid), default anthropic/claude-fable-5
- generate_image(prompt, model?) — image (paid), default google/gemini-3-pro-image
- treasury_stats()        — live fees funding open-source AI (free)
- wallet_balance()        — your $HERO + ETH (wallet mode)

Every paid tool accepts consent:true to contribute the prompt+output as opt-in open training data.

## OpenAI-compatible API (works with any OpenAI SDK / agent framework)

Base URL: https://hero-run.vercel.app/v1
Auth:     Authorization: Bearer hr_live_...   (mint at /keys)
Model:    "auto" = multi-gateway router (right-sized model, one flat price), or any /v1/models id

POST https://hero-run.vercel.app/v1/chat/completions
  {"model":"auto","messages":[{"role":"user","content":"hello"}],"stream":false}
GET  https://hero-run.vercel.app/v1/models

Drop into the OpenAI SDK by setting base_url + api_key; streaming supported.
Function calling: pass `tools` / `tool_choice` (OpenAI format) — forwarded to the
routed gateway; tool_calls come back with finish_reason "tool_calls". Send tool
results as role:"tool" messages as usual. (Tool turns respond unstreamed.)
Works with Vercel AI SDK, LangChain, CrewAI, LlamaIndex, and any OpenAI-compatible client.

## HTTP API (native, no MCP needed)

POST https://hero-run.vercel.app/api/run
  header: x-api-key: hr_live_...
  body:   {"model":"anthropic/claude-fable-5","input":"hello","kind":"text"}

Modalities (via kind on /api/run; browse GET /api/models and filter by kind):
  image — LIVE. {"model":"auto","input":"<prompt>","kind":"image"} → {"image":"data:image/png;base64,..."}
          model "auto" = flat-price image routing; or a specific id (Gemini image / GPT Image / FLUX).
  audio — LIVE. {"model":"openai/gpt-audio-mini","input":"Say hi","kind":"audio"} →
          {"audio":"data:audio/wav;base64,...","text":"<transcript>"}. Speech (gpt-audio,
          gpt-audio-mini) and music (google/lyria-3-clip-preview, lyria-3-pro-preview).
  video — LIVE. {"model":"wavespeed-ai/wan-2.2/t2v-480p-ultra-fast","input":"<prompt>","kind":"video"}
          → {"video":"<mp4 url>"}. Text-to-video via WaveSpeed (Wan 2.2, LTX-2, Kling 2.5,
          Seedance 2.0, P-Video); clips take 1-3 minutes — use a long request timeout.

Gateway pinning: append @gateway to ANY model id to force that exact provider (no failover,
billed at that gateway's own price): "openai/gpt-oss-120b@cerebras", "glm-5.2@fireworks".
Gateway ids: openrouter, cerebras, groq, cloudflare, fireworks, deepinfra, together, baseten, bfl, wavespeed.
Works in /v1, /api/run, the MCP server, and the SDKs (it's just a model id).

GET https://hero-run.vercel.app/api/models        — catalog + prices
GET https://hero-run.vercel.app/api/keys/info      — key balance (header x-api-key)

## One-paste prompt (give this to Claude)

"Set up the Hero Run MCP server for me. Download https://hero-run.vercel.app/hero-run-mcp.mjs, run `npm install viem`, then ask me for my Hero Run API key (I can mint one at https://hero-run.vercel.app/keys). Register it with `claude mcp add hero-run -e HERO_RUN_KEY=<key> -- node <abs path>/hero-run-mcp.mjs`, then list the hero-run tools to confirm. Reference: https://hero-run.vercel.app/llms.txt"