# heumpa

> An open market for AI inference. One OpenAI-compatible key and base URL; each call goes to the
> healthy seller with the biggest discount. Sign in with an Ethereum-style wallet on Robinhood Chain
> (mainnet, chain id 4663). Pay in USDG. 1 USDG = $1.00 of API balance.

STATUS: beta (HEUMPA token live). Nothing has been audited. The API at https://api.useheumpa.fun answers; models come from heumpa's own supply (32 models) plus one DeepSeek seller, and no outside seller
has joined yet. Only heumpa's own test transactions have moved money so far. Do not move real funds on the strength of this file.

## Chain
- Robinhood Chain mainnet, chain id 4663 (CAIP-2 eip155:4663), gas token ETH.
- RPC: https://rpc.mainnet.chain.robinhood.com, https://rpc-robinhood.blockmachine.io
- Explorer: https://robinhoodchain.blockscout.com
- USDG: 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168, 6 decimals. No EIP-3009, so only plain transfer is used.
- Pay from an EOA (MetaMask, Rabby, Coinbase Wallet, or a plain key). Smart-contract wallets are refused (unsupported_wallet_type).

## What exists today
- Wallet sign-in (EIP-191 personal_sign, single-use nonce, 24h session).
- API keys per wallet (max 25), each with an optional USD spend cap. A key is shown once.
- Price-based routing: sellers declare a discount (0-80%) below list price; the router prefers the biggest
  discount among healthy sellers and falls back to the next one if a call fails. A seller that refuses
  connections is disabled automatically.
- Only models with a reference price are served. An unpriced model returns HTTP 400 and costs nothing.
- Usage feed per wallet (model, tokens, cost).
- USDG top-up and x402 pay-per-request, both checked by on-chain receipt.

## What does NOT exist
- Staking is COMING SOON and not live. It ships with the heumpa token, after an independent audit. Nothing to stake today.
- No card payments, no organisations or workspaces, no webhooks, no facilitator, no x402 "exact"/"upto".
- No audit. No published uptime, volume or savings numbers. Seller payouts work (tested on mainnet with heumpa's own wallets, a daily cap applies) but have not been used by outside sellers yet.
- Not carried over on the Anthropic endpoint: extended thinking, cache_control, server tools (web search), documents. They are ignored, never faked.
- Output quality and model identity behind a seller are not verified.

## Base URLs (one host, one key)
- OpenAI format:    https://api.useheumpa.fun/v1   (/chat/completions, /completions, /embeddings, /models)
- Anthropic format: https://api.useheumpa.fun      (POST /v1/messages, POST /v1/messages/count_tokens) and https://api.useheumpa.fun/anthropic (same paths; also GET /anthropic/v1/models)
- Hosted MCP (read only): https://mcp.useheumpa.fun/mcp
A key from the app is required, sent as an Authorization Bearer header or as x-api-key. The API is NOT free: it spends the balance you add
(USDG top-up or x402). Only the in-app playground has free messages: free models refill every 4 hours; premium models (output price above $2 per
1M tokens, e.g. Claude Opus, top GPT models) are locked until the wallet has a balance, then billed to it.

## Claude Code
  export ANTHROPIC_BASE_URL="https://api.useheumpa.fun/anthropic"
  export ANTHROPIC_AUTH_TOKEN="<your heumpa key>"
  export ANTHROPIC_API_KEY=""               # blank so a cached login cannot win
  export ANTHROPIC_MODEL="<a name from GET /v1/models>"
  export ANTHROPIC_SMALL_FAST_MODEL="<a name from GET /v1/models>"
Pin BOTH model variables. The model name must have a live seller or the call returns 404 not_found_error. Tested with the real Claude Code CLI
(an agent task using its Read tool), and with the official Anthropic SDK for streaming and tool use. Other OpenAI-format tools (Cursor, Cline,
Continue, Aider, OpenCode): set the base URL to https://api.useheumpa.fun/v1, the key to your heumpa key, the model to a name from /v1/models.

## Routing (measured)
For one model the router picks the healthy seller with the deepest discount; equal discounts share traffic at random; if a call fails it is retried
on a different seller. Winner-takes-all: a 10% seller receives nothing while a healthy 20% seller exists, and takes over if that seller breaks.
Each live offer is probed every 10 minutes; two failures in a row pause it.

## Authentication for software agents
1. POST {bridge}/v1/auth/nonce      {"wallet":"<lowercase 0x address>"}  -> {"message":"..."}
   The message is exactly five lines: "Sign in to heumpa", "Wallet: <address>", "Chain: 4663", "Nonce: <32 hex>", "Expires: <ISO time>".
   Refuse to sign anything that does not match.
2. personal_sign the message (EIP-191). The signature is 0x + 130 hex.
3. POST {bridge}/v1/auth/verify     {"wallet":"...","signature":"0x..."} -> {"token":"..."}
4. Send "Authorization: Bearer <token>" on later calls. A nonce works once, pass or fail.

## Endpoints (bridge)
- GET  /v1/market                    public: models, seller counts, best discount
- GET  /v1/stats                     public: sellers, healthy sellers, models, processed top-ups
- GET  /v1/me                        balance_usd, used_usd, top-up history
- GET  /v1/keys                      masked keys, caps, spend
- POST /v1/keys                      {"name":"agent-1","limit_usd":25|null} -> {"key":"sk-..."} (shown once)
- DELETE /v1/keys/{id}               revoke
- GET  /v1/usage                     recent calls and daily totals
- POST /v1/sell/discover              {"provider","key","endpoint"?}  -> models behind the key, each with its heumpa id and list price (in/out per 1M)
- POST /v1/sell/health                {"provider","key","models"[<=6]}  one small request per model on the seller's own key
- POST /v1/sell/apply                 {"provider","key","name","models":[...],"discount_percent"(0-80)}  publishes at once if the key works
- GET  /v1/sell/offers                the caller's offers with list price and buyer price per model
\1- GET  /v1/sell/earnings?days=30      sales of the caller's own offers (no buyer data)
- GET  /v1/sell/payouts               {earned_usd, paid_usd, pending_usd, available_usd, held_usd, hold_hours, ...}
- POST /v1/sell/payouts               request a withdrawal of the available balance, paid as USDG to the signed-in wallet only (5 per hour)

## Inference
OpenAI format: POST https://api.useheumpa.fun/v1/chat/completions with an Authorization Bearer header holding your key. Streaming and tool calls work.
Errors (OpenAI shape): 401 bad or revoked key; 403 balance too low; 400 model not priced. Anthropic endpoint errors use Anthropic's shape:
401 authentication_error, 404 not_found_error (no live seller for that model), 400 invalid_request_error (also "credit balance is too low"),
429 rate_limit_error, 529 overloaded_error. Request body limit 8 MB. Each key: 600 requests per minute.

## Add balance with USDG
The server never holds your keys or broadcasts for you; it only reads the receipt.
1. GET  {bridge}/v1/topup/info                       -> asset (USDG), payTo, min_usd 1, max_usd 500
2. POST {bridge}/v1/topup/quote  {"usd":5}           -> {quote_id, network:"eip155:4663", asset, payTo, decimals:6, amount (atomic), calldata_suffix, expires_at}  (session required)
3. From an EOA send ONE tx to the USDG contract with data =
   0xa9059cbb + payTo padded to 32 bytes + amount padded to 32 bytes + calldata_suffix (without 0x).  (USDG ignores the trailing bytes.)
4. POST {bridge}/v1/topup/claim {"quote_id","tx_hash"} -> {ok, credited_usd, tx_hash}. The payer must be the signed-in wallet.
   The server waits for confirmations, so a very fresh tx may need a retry.
Rules: one payment credits once (even if claimed twice at once); overpay is credited as received; a payment made by a
different wallet cannot be claimed into your account; one transaction can be spent once across top-up AND x402.

## Pay per request without an account (x402)
GET {bridge}/x402/info -> {enabled, schemes:["transfer-receipt"], network, asset, payTo, minimum_usd, endpoints, note}.
POST {bridge}/x402/v1/chat/completions {"model","messages","max_tokens"<=1024}  (no streaming) -> 402 with PAYMENT-REQUIRED
(base64 JSON) and the same in the body: accepts[0] = {scheme:"transfer-receipt", network:"eip155:4663", asset, payTo, amount,
maxTimeoutSeconds, extra:{memo (= quote id), calldata_suffix, name:"USDG", decimals:6, howTo}}.
Pay: ONE USDG transfer(payTo, amount) from an EOA with data = selector + payTo + amount + calldata_suffix (as above).
Then repeat the identical request with
PAYMENT-SIGNATURE = base64(JSON {"x402Version":2,"accepted":<accepts[0]>,"payload":{"quoteId":<extra.memo>,"txHash":<0x tx hash>}}).
Reference client: sdk/pay.mjs (HEUMPA_URL, PAYER_KEY_FILE, MAX_USDG).
Rules: a quote is bound to the exact body, single-use, valid 5 minutes. One payment buys one request. Wrong amount, token,
payee, reference, or a forged transaction -> 402. 409 = already used. 502 after payment = recorded as refund due.
Status: HEUMPA token live (0x222de1c29b7ec256d4fd2003678a479b104ca90d on Robinhood Chain 4663); product in beta; not audited.

## Seller payouts
Each call an offer serves is one ledger row. The seller earns the buyer charge minus a 10% platform fee. Earnings are withdrawable 24 hours after
the sale, minimum 1 USD, paid in USDG to the wallet used to sign in (never another address); heumpa pays the network fee. Not realtime. The
payout path was tested on mainnet, including crash recovery (paid once each time). Nothing here promises income: see /docs/seller-economics.

## MCP
Hosted read-only server: https://mcp.useheumpa.fun/mcp (Streamable HTTP, stateless). Tools: heumpa_status, heumpa_models, heumpa_catalog,
heumpa_topup_info, heumpa_quote, heumpa_spend. It cannot spend. The package @heumpa/mcp@0.1.0 is on npm: `claude mcp add heumpa -- npx -y @heumpa/mcp`. It adds heumpa_chat (needs HEUMPA_API_KEY) and
heumpa_pay (needs HEUMPA_WALLET_KEY_FILE, a mode-600 file); pay is a dry run until confirm:true and the receiving address is pinned. With no
credentials it has the same six read-only tools as the hosted server.

## Money
1 USDG = $1 of API balance. The balance cannot be transferred or withdrawn. Amounts in the app are shown in USD.

## Docs
https://useheumpa.fun/docs  (claude-code, other-tools, mcp, routing, payouts, seller-economics, verification, x402, api-reference, errors, security)