# heura

> 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: pre-launch. Nothing has been audited and no customer funds have moved. The API at https://api.useheura.com/v1
answers and one seller (run by heura) is connected. 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 (Phantom, MetaMask, Rabby, 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, NEX and CREDIT were REMOVED. They return only after a Solidity version is written and audited.
- 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 heura's own wallets, a daily cap applies) but have not been used by outside sellers yet.

## Base URL
Base URL: https://api.useheura.com/v1 (OpenAI-compatible: /chat/completions, /completions, /embeddings, /models). A key from the app is required. One seller is connected so far (run by heura) and nothing has been audited.

## Authentication for software agents
1. POST {bridge}/v1/auth/nonce      {"wallet":"<lowercase 0x address>"}  -> {"message":"..."}
   The message is exactly five lines: "Sign in to heura", "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 heura 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
- PATCH /v1/sell/offers/{id}          {"discount_percent"?|"paused"?}  owner only; DELETE removes it and deletes the stored key

## Inference
OpenAI format: POST {gateway}/v1/chat/completions with "Authorization: Bearer <heura key>".
Errors: 401 bad or revoked key; 403 balance too low; 400 model not priced.

## 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 (HEURA_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: not launched, not audited.

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