# envolvr

> Private, verifiable AI inference for agents on Robinhood Chain. An OpenAI-compatible API that runs inside hardware-attested enclaves (Intel TDX gateway, confidential-GPU providers). Every response comes with a signed receipt (model, attested provider session, request and response commitments, amount billed), and receipts are anchored on Robinhood Chain every 10 minutes.

## Endpoints

- Inference gateway: https://api.envolvr.xyz (OpenAI API: POST /v1/chat/completions, GET /v1/models)
- Accounts and proofs: https://auth.envolvr.xyz
- Human docs: https://envolvr.xyz/docs/
- Source: https://github.com/envolvr/envolvr (SDK in sdk/), https://github.com/envolvr/private-ai-gateway

## Get an API key (wallet sign-in)

1. GET https://auth.envolvr.xyz/auth/nonce?wallet=<0x address> returns {nonce, issuedAt, message}.
2. Sign `message` with EIP-191 personal_sign using that wallet.
3. POST https://auth.envolvr.xyz/auth/key with JSON {wallet, nonce, issuedAt, signature} returns {apiKey}. Shown once. Send it as `Authorization: Bearer <apiKey>`.

## Fund the account

- In a browser: https://envolvr.xyz/app/ (connect a wallet; deposit, manage keys, see usage, close).
- USDG deposit: approve the CreditVault for USDG, then call deposit(uint256 amount) (or depositFor(address account, uint256 amount)). USDG has 6 decimals. Credited within seconds, net of the deposit fee (GET https://auth.envolvr.xyz/pricing -> depositFeeBps; currently 500 = 5%). A plain token transfer to the vault is not credited.
- Automatic top-up (SDK): new Envolvr({ apiKey, autoTopUp: { signer, below: '5', amount: '20', maxPerDay: '100' } }) deposits `amount` when the balance < `below`, waits for the credit, and retries a 402 once; capped per UTC day.
- Manage keys: GET https://auth.envolvr.xyz/auth/session/nonce?wallet=<0x> -> {message}; sign it (EIP-191); POST https://auth.envolvr.xyz/auth/session {wallet, nonce, issuedAt, signature} -> {session} (12 hours; manages the account, cannot call models). With `Authorization: Bearer <session>`: GET/POST /account/keys ({label}), POST /account/keys/revoke {id}, GET /account/usage, GET /account/deposits.
- Balance: GET https://auth.envolvr.xyz/account with the API key -> {balanceMicros} (micro-USD).
- Close and refund: GET https://auth.envolvr.xyz/account/close/nonce?wallet=<0x>&refundTo=<0x> -> {message}; sign it with the wallet (EIP-191); POST https://auth.envolvr.xyz/account/close {wallet, refundTo, nonce, issuedAt, signature}. Revokes every API key and refunds the balance to refundTo (default: the wallet), paid from the credit vault shortly after. Deposit fees are not refunded.

## Call a model

POST https://api.envolvr.xyz/v1/chat/completions with an OpenAI chat body. Optional routing: "provider": {"only": ["near-ai"]} or {"order": ["redpill","near-ai"], "allow_fallbacks": true}. Providers: redpill (Phala), near-ai (NEAR AI Cloud), chutes (Chutes on Bittensor; each machine verified individually, requests end-to-end encrypted to its attested key). The response header x-receipt-id names the receipt; usage.cost is the cost in USD.

Models at launch (input / output USD per 1M tokens; GET /v1/models is authoritative):
- z-ai/glm-5.3: Phala via RedPill, 1.40 / 4.40
- z-ai/glm-5.3-flash: NEAR AI (non-streamed responses signed by the model enclave), 0.15 / 0.50
- qwen/qwen3.8-27b: Chutes 0.24 / 2.20; on request Phala via RedPill 0.24 / 2.50 or NEAR AI 0.44 / 3.30
- qwen/qwen3.6-35b-a3b: NEAR AI, 0.17 / 1.10
- deepseek/deepseek-v4-flash: Chutes, 0.44 / 1.32
- deepseek/deepseek-v3.2: Chutes, 1.00 / 1.00
- moonshotai/kimi-k2.6: Chutes, 0.50 / 2.85

## Receipts

GET https://api.envolvr.xyz/v1/aci/receipts/<x-receipt-id> with the same API key, within one hour (receipts are kept for an hour). Events: request.received (sha256 of the request bytes), route.selected, upstream.verified (attested provider session), upstream.response_attested (NEAR, non-streamed), billing.charged ({currency, cost as decimal string, billed_micro_usd, rates, tokens, payer}), response.returned (sha256 of the response bytes). Signed with an Ed25519 key from the gateway's attested keyset.

payer = "sha256:" + hex(sha256("billing.payer.v1:" + hex(sha256(api_key)) + ":" + receipt_id))

## Verify

- Gateway: npx private-ai-proxy verify https://api.envolvr.xyz --require-production-os
- Receipt signature and commitments: npx private-ai-proxy audit --report <attestation.json> --receipt <receipt.json> --request-body <request.json> --response-body <response.json> --session <session.json>
  (attestation.json: GET https://api.envolvr.xyz/v1/aci/attestation?nonce=<64 hex>, fetched while the receipt's keyset is live; session.json: GET /v1/aci/sessions/<session_id> with the API key)
- Anchor: digest = "0x" + hex(sha256(JCS(receipt))) (RFC 8785). GET https://auth.envolvr.xyz/receipts/<digest>/proof -> {status, batchIndex, leafIndex, root, proof, txHash}. Then call ReceiptAnchor.verifyReceipt(providerId, batchIndex, digest, proof) -> true. Anchored in 10-minute UTC slots, seconds after each slot ends.
- The SDK does all of it: `npx @envolvr/sdk verify --last` (npm package @envolvr/sdk; also signin, deposit, chat, close). Always use the scoped name with npx.

## Robinhood Chain (chain id 4663)

- RPC: https://rpc.mainnet.chain.robinhood.com
- Explorer: https://robinhoodchain.blockscout.com
- USDG, CreditVault, NVLR, ReceiptAnchor: addresses at https://envolvr.xyz/token/#contracts
- Gateway provider id: 0x86b99987cd8f8ebddc2dd0efa61ed52b5db594430f12446db424da0d9c4b831f

## NVLR

- ERC-20 on Robinhood Chain, 1,000,000,000 supply. Not needed to use envolvr: USDG pay-per-request needs no token.
- Buyback and burn: a portion of protocol revenue buys back NVLR and burns it, on an ongoing basis.
- Details: https://envolvr.xyz/token/

## Pricing

Tokens at the providers' list prices. A fee (currently 5%) is kept from each USDG deposit. Billing is the exact cost rounded up to the next micro-USD. A request that allows several providers is priced at the highest of their list prices.