{"openapi":"3.1.0","info":{"title":"Verathos Validator Proxy","version":"0.1.25"},"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/capacity/audit/v1/health":{"get":{"summary":"Capacity Audit Health","operationId":"capacity_audit_health_capacity_audit_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/subnet-config":{"get":{"summary":"Subnet Config","operationId":"subnet_config_v1_subnet_config_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/capacity/audit/v1/receipt":{"post":{"summary":"Capacity Audit Receipt","operationId":"capacity_audit_receipt_capacity_audit_v1_receipt_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/capacity/audit/v1/proof":{"post":{"summary":"Capacity Audit Proof","operationId":"capacity_audit_proof_capacity_audit_v1_proof_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/supply/circulating":{"get":{"summary":"Supply Circulating","description":"Circulating alpha supply: alpha_in_pool + alpha_staked.","operationId":"supply_circulating_v1_supply_circulating_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/v1/supply/total":{"get":{"summary":"Supply Total","description":"Total alpha supply reported to listing APIs.","operationId":"supply_total_v1_supply_total_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/v1/supply/max":{"get":{"summary":"Supply Max","description":"Max alpha supply: 21,000,000 (hard cap, same as TAO).","operationId":"supply_max_v1_supply_max_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/v1/supply/info":{"get":{"summary":"Supply Info","description":"Rich supply data for dashboards (not for CMC/CoinGecko polling).","operationId":"supply_info_v1_supply_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/miner-debug/help":{"get":{"summary":"Miner Debug Help","operationId":"miner_debug_help_v1_miner_debug_help_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/miner-debug/{uid}":{"get":{"summary":"Miner Debug","operationId":"miner_debug_v1_miner_debug__uid__get","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"integer","title":"Uid"}},{"name":"window_h","in":"query","required":false,"schema":{"type":"integer","maximum":48,"minimum":1,"default":24,"title":"Window H"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/miner-debug/{uid}/entries/{model_index}":{"get":{"summary":"Miner Debug Entry","operationId":"miner_debug_entry_v1_miner_debug__uid__entries__model_index__get","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"integer","title":"Uid"}},{"name":"model_index","in":"path","required":true,"schema":{"type":"integer","title":"Model Index"}},{"name":"window_h","in":"query","required":false,"schema":{"type":"integer","maximum":48,"minimum":1,"default":24,"title":"Window H"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/network/stats":{"get":{"summary":"Network Stats","description":"Network-wide statistics for the dashboard.\n\nCombines miner pool state, health, scores, organic traffic stats,\nand probation info into a single response.","operationId":"network_stats_v1_network_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/network/usage-timeseries":{"get":{"summary":"Usage Timeseries","description":"Time-bucketed usage data for dashboard charts.","operationId":"usage_timeseries_v1_network_usage_timeseries_get","parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","default":"24h","title":"Range"}},{"name":"model_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tee/info":{"get":{"summary":"Tee Info","description":"Return TEE enclave info for a miner serving *model*.\n\nThe client uses the returned ``enclave_public_key`` to encrypt requests\nsent to ``/v1/tee/chat/completions``.  The ``miner_address`` field lets\nthe proxy pin-route the encrypted request to this exact miner.","operationId":"tee_info_tee_info_get","parameters":[{"name":"model","in":"query","required":false,"schema":{"type":"string","default":"auto","title":"Model"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/models":{"get":{"summary":"List Models","description":"List available models with USD pricing.\n\nIn multi-miner mode, only shows models that have live miners.","operationId":"list_models_v1_models_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/price":{"get":{"summary":"Get Price","description":"Compute the cost for a hypothetical request.\n\nQuery parameters:\n    model: Registry model ID or HuggingFace model path\n    input_tokens: Number of prompt tokens\n    output_tokens: Number of generated tokens\n    verified: Whether proof verification is included (25% premium)","operationId":"get_price_v1_price_get","parameters":[{"name":"model","in":"query","required":false,"schema":{"type":"string","default":"qwen2.5-7b-instruct","title":"Model"}},{"name":"input_tokens","in":"query","required":false,"schema":{"type":"integer","default":1000,"title":"Input Tokens"}},{"name":"output_tokens","in":"query","required":false,"schema":{"type":"integer","default":500,"title":"Output Tokens"}},{"name":"verified","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Verified"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/challenge":{"get":{"summary":"Get Challenge","description":"Get a challenge string for wallet signature verification.","operationId":"get_challenge_v1_auth_challenge_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/register":{"post":{"summary":"Register Email","description":"Register a new user with email/password.\n\nReturns API key on success. No wallet required.","operationId":"register_email_v1_auth_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailRegisterRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/login":{"post":{"summary":"Login Email","description":"Validate email/password credentials. Returns {user_id, email} — no key created.","operationId":"login_email_v1_auth_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailLoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/keys":{"post":{"summary":"Create Key Email","description":"Validate email/password and create a new API key. Returns {user_id, email, api_key}.","operationId":"create_key_email_v1_auth_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailLoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/api-keys":{"get":{"summary":"List Api Keys","description":"List API keys for the authenticated user.","operationId":"list_api_keys_v1_api_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Create Api Key","description":"Authenticate with wallet signature and create API key.\n\n1. Verify the challenge is valid (not expired)\n2. Recover signer from EIP-191 signature\n3. Check signer matches claimed address\n4. Auto-register wallet user if new\n5. Generate and return API key","operationId":"create_api_key_v1_api_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAPIKeyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/wallet":{"post":{"summary":"Create Api Key","description":"Authenticate with wallet signature and create API key.\n\n1. Verify the challenge is valid (not expired)\n2. Recover signer from EIP-191 signature\n3. Check signer matches claimed address\n4. Auto-register wallet user if new\n5. Generate and return API key","operationId":"create_api_key_v1_auth_wallet_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAPIKeyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/api-keys/{key_hash}":{"delete":{"summary":"Revoke Api Key","description":"Revoke an API key.","operationId":"revoke_api_key_v1_api_keys__key_hash__delete","parameters":[{"name":"key_hash","in":"path","required":true,"schema":{"type":"string","title":"Key Hash"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/x402/stats":{"get":{"summary":"X402 Admin Stats","description":"x402 aggregation health snapshot for operator monitoring.\n\nAdmin-only: requires X-Admin-Token header matching VERATHOS_ADMIN_TOKEN env var.\n\nReturns row counts grouped by status, pending settle volume, and\ncounters for stuck rows (high failure count) or rows about to expire.","operationId":"x402_admin_stats_v1_admin_x402_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/admin/sponsored-keys":{"post":{"summary":"Create Sponsored Key","description":"Create a sponsored API key (no payment required).\n\nAdmin-only: requires X-Admin-Token header matching VERATHOS_ADMIN_TOKEN env var.\n\nBody: {\"name\": \"webapp-demo\", \"address\": \"0x...\"}","operationId":"create_sponsored_key_v1_admin_sponsored_keys_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/deposit-info":{"get":{"summary":"Deposit Info","description":"Return the info a client needs to deposit TAO for inference credits.\n\nThe ``validator_hotkey`` is the default staking target — deposits that\ndon't specify a hotkey should stake to this validator (the one that\noperates this proxy).","operationId":"deposit_info_v1_deposit_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/balance":{"get":{"summary":"Get Balance","description":"Get credit balance for the authenticated user.","operationId":"get_balance_v1_balance_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/usage":{"get":{"summary":"Get Usage","description":"Get usage log for the authenticated user.","operationId":"get_usage_v1_usage_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/user/me":{"get":{"summary":"Get Current User","description":"Return basic info about the authenticated user.\n\nUseful for the webapp to validate a stored API key on page load.\nReturns 401 if the key is missing or invalid.","operationId":"get_current_user_v1_user_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/user/deposit-address":{"get":{"summary":"Get Deposit Address","description":"Get per-user deposit addresses for TAO (Bittensor) and USDC/ETH (Base).\n\nEach user gets unique deposit addresses. Send TAO to the SS58 address,\nor USDC/ETH to the Base EVM address. Credits appear within 30 seconds.","operationId":"get_deposit_address_v1_user_deposit_address_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/user/withdraw":{"post":{"summary":"Withdraw","description":"Withdraw unconsumed TAO or USDC from deposit address.","operationId":"withdraw_v1_user_withdraw_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/deposits/base/verify":{"post":{"summary":"Verify Base Deposit","description":"Verify a USDC or ETH deposit on Base and credit the user's balance.\n\nThe user must first send USDC or ETH to the validator's Base deposit\naddress (returned by ``GET /v1/deposit-info``), then call this endpoint\nwith the transaction hash.","operationId":"verify_base_deposit_v1_deposits_base_verify_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseVerifyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/deposits/base":{"get":{"summary":"List Base Deposits","description":"List the authenticated user's Base deposits.","operationId":"list_base_deposits_v1_deposits_base_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/chat/completions":{"post":{"summary":"Plaintext Chat","description":"OpenAI-compatible chat completions with streaming, model routing, failover, and proof verification.","operationId":"plaintext_chat_v1_chat_completions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaintextChatRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tee/chat/completions":{"post":{"summary":"Encrypted Chat","description":"TEE-encrypted inference with failover: relay encrypted envelope to miner,\nverify proofs, return encrypted output.\n\nNon-streaming: returns JSON with encrypted_output (full response) and\nencrypted_chunks (per-token encrypted deltas for client-side replay).","operationId":"encrypted_chat_v1_tee_chat_completions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EncryptedChatRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tee/chat/completions/stream":{"post":{"summary":"Encrypted Chat Stream","description":"TEE-encrypted inference with SSE streaming and failover.\n\nRelays encrypted token chunks as SSE ``encrypted_token`` events in\nreal-time, then a final ``done`` event with proof verification result.\nThe validator verifies proofs but cannot decrypt any content.","operationId":"encrypted_chat_stream_v1_tee_chat_completions_stream_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StreamEncryptedChatRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/debug/chat/completions":{"post":{"summary":"Debug Chat","description":"Chat completions pinned to a specific miner.\n\nTarget by ``?hotkey=SS58`` or ``?endpoint=URL`` (for multi-endpoint miners).\nAdmin-only: requires X-Admin-Token header matching VERATHOS_ADMIN_TOKEN env var.\nNo failover — if the miner fails, the error is returned directly.","operationId":"debug_chat_v1_debug_chat_completions_post","parameters":[{"name":"hotkey","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SS58 hotkey of the miner to target","title":"Hotkey"},"description":"SS58 hotkey of the miner to target"},{"name":"endpoint","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Endpoint URL of the miner to target","title":"Endpoint"},"description":"Endpoint URL of the miner to target"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaintextChatRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"BaseVerifyRequest":{"properties":{"tx_hash":{"type":"string","title":"Tx Hash"}},"type":"object","required":["tx_hash"],"title":"BaseVerifyRequest"},"CreateAPIKeyRequest":{"properties":{"address":{"type":"string","title":"Address"},"challenge":{"type":"string","title":"Challenge"},"signature":{"type":"string","title":"Signature"},"name":{"type":"string","title":"Name","default":""}},"type":"object","required":["address","challenge","signature"],"title":"CreateAPIKeyRequest","description":"Request to create an API key with wallet signature proof."},"EmailLoginRequest":{"properties":{"email":{"type":"string","title":"Email"},"password":{"type":"string","title":"Password"}},"type":"object","required":["email","password"],"title":"EmailLoginRequest","description":"Request to login with email/password."},"EmailRegisterRequest":{"properties":{"email":{"type":"string","title":"Email"},"password":{"type":"string","title":"Password"}},"type":"object","required":["email","password"],"title":"EmailRegisterRequest","description":"Request to register a new user with email/password."},"EncryptedChatRequest":{"properties":{"session_id":{"type":"string","title":"Session Id"},"sender_public_key":{"type":"string","title":"Sender Public Key"},"nonce":{"type":"string","title":"Nonce"},"ciphertext":{"type":"string","title":"Ciphertext"},"content_type":{"type":"string","title":"Content Type","default":"application/json"},"model":{"type":"string","title":"Model","default":"auto"},"target_enclave_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Enclave Key"}},"type":"object","required":["session_id","sender_public_key","nonce","ciphertext"],"title":"EncryptedChatRequest","description":"TEE-encrypted chat request from user."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PlaintextChatRequest":{"properties":{"messages":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Messages"},"model":{"type":"string","title":"Model","default":""},"max_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Tokens"},"max_new_tokens":{"type":"integer","title":"Max New Tokens","default":4096},"stream":{"type":"boolean","title":"Stream","default":false},"do_sample":{"type":"boolean","title":"Do Sample","default":false},"temperature":{"type":"number","title":"Temperature","default":1.0},"enable_thinking":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enable Thinking"},"include_proof":{"type":"boolean","title":"Include Proof","default":true},"presence_penalty":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Presence Penalty"},"top_k":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top K"},"top_p":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top P"},"min_p":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min P"},"sampling_verification_bps":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sampling Verification Bps"},"tools":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Tools"},"tool_choice":{"anyOf":[{},{"type":"null"}],"title":"Tool Choice"},"parallel_tool_calls":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Parallel Tool Calls"}},"type":"object","required":["messages"],"title":"PlaintextChatRequest","description":"OpenAI-compatible chat completion request (forwarded to miner /chat)."},"StreamEncryptedChatRequest":{"properties":{"session_id":{"type":"string","title":"Session Id"},"sender_public_key":{"type":"string","title":"Sender Public Key"},"nonce":{"type":"string","title":"Nonce"},"ciphertext":{"type":"string","title":"Ciphertext"},"content_type":{"type":"string","title":"Content Type","default":"application/json"},"model":{"type":"string","title":"Model","default":"auto"},"target_enclave_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Enclave Key"}},"type":"object","required":["session_id","sender_public_key","nonce","ciphertext"],"title":"StreamEncryptedChatRequest","description":"Same as EncryptedChatRequest — separate model for the streaming endpoint."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WithdrawRequest":{"properties":{"amount_tao":{"type":"string","title":"Amount Tao","default":"0"},"amount_usdc":{"type":"string","title":"Amount Usdc","default":"0"},"destination":{"type":"string","title":"Destination"}},"type":"object","required":["destination"],"title":"WithdrawRequest"}}}}