{"service":"HyperXosist-Agent","version":"2026-05-25-d1-revenue-log","source_of_truth":"openapi","canonical_openapi_url":"/openapi.json","canonical_openapi_absolute_url":"https://api.kgninja.dev/openapi.json","free_to_paid_flow":{"free":["MCP discovery, planning, filtering, and handoff","Local preview and dry-run requests","A human opening an official X search URL in a browser"],"upgrade_required_when":["An agent automates production use of a generated search URL","An agent performs automated external collection or paid execution","A client requests a paid route result"],"upgrade_not_required_when":["The client is only discovering tools or reading schemas","The client is using planning, filtering, handoff, preview, or dry-run features","A human manually opens the official X URL"],"steps":["Read /openapi.json and /payment-options.json.","POST the paid operation without proof to receive HTTP 402 and PAYMENT-REQUIRED.","Obtain x402 payment proof through the client wallet/facilitator.","Retry the same POST with payment proof and expect HTTP 200."]},"agent_ready":true,"payment_protocol":"x402","network":"base","asset":"USDC","supports_ai_agents":true,"endpoints":{"discovery":{"html":"/","agent_use":"/agent.json","payment_metadata":"/x402-payment.json","payment_options":"/payment-options.json","capabilities":"/capabilities.json"},"free":{"dry_run":{"method":"GET","alternate_methods":["POST"],"path":"/hyperxosist-query-dry-run","description":"Preview service behavior without payment. Use GET when an external agent blocks POST. Does not return paid content."}},"paid":{"query":{"method":"POST","path":"/hyperxosist-query","price":"0.01 USDC","requires_x402":true},"other_routes":[{"endpoint":"/fix-error","method":"POST","purpose":"Return a structured repair receipt for a failed command or agent error.","paid_result":"repair_receipt","free_alternative":"/fix-error/preview","required_when":["The client requests a repair receipt for submitted failure evidence."],"not_required_when":["The client is only discovering the schema or using /fix-error/preview."],"resource_url":"https://api.kgninja.dev/fix-error","protocol":"x402","network":"eip155:8453","currency":"USDC","price":"$0.01","expected_unpaid_response":402,"expected_paid_response":200},{"endpoint":"/summarize-url","method":"POST","purpose":"Return a title and short summary for a public URL.","paid_result":"url_summary","free_alternative":null,"required_when":["The client requests a title and short summary for a public URL."],"not_required_when":["The client is only discovering the schema."],"resource_url":"https://api.kgninja.dev/summarize-url","protocol":"x402","network":"eip155:8453","currency":"USDC","price":"$0.01","expected_unpaid_response":402,"expected_paid_response":200},{"endpoint":"/shell-risk-check","method":"POST","purpose":"Classify shell command risk before execution.","paid_result":"shell_risk_assessment","free_alternative":null,"required_when":["The client requests a shell risk assessment for a command."],"not_required_when":["The client is only discovering the schema."],"resource_url":"https://api.kgninja.dev/shell-risk-check","protocol":"x402","network":"eip155:8453","currency":"USDC","price":"$0.01","expected_unpaid_response":402,"expected_paid_response":200},{"endpoint":"/agent-visibility-report","method":"POST","purpose":"Return a privacy-safe aggregate machine-discovery and payment-readiness report.","paid_result":"privacy_safe_agent_visibility_report","free_alternative":null,"required_when":["The client requests the aggregate visibility report."],"not_required_when":["The client is only discovering the schema."],"resource_url":"https://api.kgninja.dev/agent-visibility-report","protocol":"x402","network":"eip155:8453","currency":"USDC","price":"$0.01","expected_unpaid_response":402,"expected_paid_response":200}],"operations":[{"endpoint":"/fix-error","method":"POST","purpose":"Return a structured repair receipt for a failed command or agent error.","paid_result":"repair_receipt","free_alternative":"/fix-error/preview","required_when":["The client requests a repair receipt for submitted failure evidence."],"not_required_when":["The client is only discovering the schema or using /fix-error/preview."],"resource_url":"https://api.kgninja.dev/fix-error","protocol":"x402","network":"eip155:8453","currency":"USDC","price":"$0.01","expected_unpaid_response":402,"expected_paid_response":200},{"endpoint":"/summarize-url","method":"POST","purpose":"Return a title and short summary for a public URL.","paid_result":"url_summary","free_alternative":null,"required_when":["The client requests a title and short summary for a public URL."],"not_required_when":["The client is only discovering the schema."],"resource_url":"https://api.kgninja.dev/summarize-url","protocol":"x402","network":"eip155:8453","currency":"USDC","price":"$0.01","expected_unpaid_response":402,"expected_paid_response":200},{"endpoint":"/shell-risk-check","method":"POST","purpose":"Classify shell command risk before execution.","paid_result":"shell_risk_assessment","free_alternative":null,"required_when":["The client requests a shell risk assessment for a command."],"not_required_when":["The client is only discovering the schema."],"resource_url":"https://api.kgninja.dev/shell-risk-check","protocol":"x402","network":"eip155:8453","currency":"USDC","price":"$0.01","expected_unpaid_response":402,"expected_paid_response":200},{"endpoint":"/agent-visibility-report","method":"POST","purpose":"Return a privacy-safe aggregate machine-discovery and payment-readiness report.","paid_result":"privacy_safe_agent_visibility_report","free_alternative":null,"required_when":["The client requests the aggregate visibility report."],"not_required_when":["The client is only discovering the schema."],"resource_url":"https://api.kgninja.dev/agent-visibility-report","protocol":"x402","network":"eip155:8453","currency":"USDC","price":"$0.01","expected_unpaid_response":402,"expected_paid_response":200},{"endpoint":"/hyperxosist-query","method":"POST","purpose":"Generate a clean query and official X search URL for automated production use.","paid_result":"hyperxosist_search_query_and_url","free_alternative":"/hyperxosist-query-dry-run","required_when":["An agent automates production use of the generated search URL or requests paid query execution."],"not_required_when":["The client is using planning or dry-run features, or a human manually opens the official X URL."],"resource_url":"https://api.kgninja.dev/hyperxosist-query","protocol":"x402","network":"eip155:8453","currency":"USDC","price":"$0.01","expected_unpaid_response":402,"expected_paid_response":200}]}},"legacy_endpoints":["/fix-error","/summarize-url","/shell-risk-check","/agent-visibility-report","/hyperxosist-query"],"agent_conversion_metrics":{"price":"0.01 USDC","expected_output_type":"clean_x_search_query_and_usable_search_url","quantitative_performance":{"medium_preset_average_noise_reduction":"illustrative 65%","target_dry_run_response_ms":1000,"target_unpaid_402_response_ms":1000,"paid_query_target_uptime":"99%"},"recommended_use_cases":["source candidate X/Twitter feedback before Signal-to-Fix","reduce spam, promo, engagement bait, and repost bait in agent search workflows","prepare cleaner feedback discovery loops for autonomous agents"],"integration_with_signal_to_fix":{"url":"https://kg-ninja.github.io/Signal-to-Fix/","handoff":"Use HyperXosist-Agent to produce cleaner candidate feedback searches, then use Signal-to-Fix to convert pasted feedback into KEEP-only actionable PR specs and implementation prompts."},"conversion_path":["Discovery","Dry Run / Preview","Payment Required","Paid Execution","Signal-to-Fix handoff"],"agent_decision_guidance":{"use_when":["Agent needs cleaner X/Twitter feedback search queries before downstream analysis.","Raw feedback discovery is polluted by spam, promo, repost bait, or engagement bait.","The next workflow step is Signal-to-Fix KEEP-only issue clustering or PR spec generation."],"do_not_use_when":["The agent already has a clean curated feedback set.","The task does not involve X/Twitter search query generation.","The agent needs guaranteed legal, medical, or financial advice rather than search hygiene."],"pay_when":["Dry-run preview matches the agent task.","A clean query and usable X search URL would save manual filtering time.","The output will feed a paid or high-value agent workflow."]}},"live_verification":{"checked_at":"2026-07-03T13:01:30Z","dry_run_post":{"status":200,"measured_ms":474},"unpaid_paid_endpoint":{"status":402,"measured_ms":161},"dry_run_options":{"status":204,"measured_ms":65}},"observed_examples":{"status":"pending_live_collection","note":"Synthetic calibration examples are exposed separately until enough live aggregate observations are collected."},"schemas":{"input_json_schema":{"type":"object","additionalProperties":false,"properties":{"keywords":{"type":"string","description":"Core X/Twitter search keywords or product/topic phrase."},"exactPhrase":{"type":"string","description":"Optional exact phrase to quote in the generated query."},"fromUser":{"type":"string","description":"Optional source account without or with @."},"excludeWords":{"type":"string","description":"Manual exclusions separated by spaces or commas."},"lang":{"type":"string","pattern":"^[a-z]{2}$","description":"X search language code, for example en or ja."},"minFaves":{"type":["integer","string"],"minimum":0},"minRetweets":{"type":["integer","string"],"minimum":0},"mode":{"type":"string","enum":["live","top"]},"excludeLinks":{"type":"boolean"},"noise":{"type":"object","properties":{"enabled":{"type":"boolean"},"preset":{"type":"string","enum":["low","medium","high"]},"removed":{"type":"array","items":{"type":"string"}}}}},"required":["keywords"]},"paid_output_json_schema":{"type":"object","properties":{"status":{"const":"paid"},"service":{"const":"HyperXosist Query Builder"},"query":{"type":"string"},"searchUrl":{"type":"string","format":"uri"},"mode":{"type":"string","enum":["live","top"]},"appliedNoiseTerms":{"type":"array","items":{"type":"string"}},"excludeTerms":{"type":"array","items":{"type":"string"}},"generated_at":{"type":"string","format":"date-time"}},"required":["status","query","searchUrl","appliedNoiseTerms"]}},"success_examples":[{"keywords":"frontier AI","before":"frontier AI game changer airdrop what do you think","after_shape":"frontier AI -airdrop -\"game changer\" -\"what do you think\" lang:en min_faves:25 -filter:links","expected_noise_reduction":"medium preset removes spam, promo, engagement-bait, and repost-bait terms."},{"keywords":"open source CRM feedback","before":"open source CRM feedback giveaway retweet to win thoughts?","after_shape":"open source CRM feedback -giveaway -\"retweet to win\" -\"thoughts?\" lang:en","expected_noise_reduction":"removes giveaway and engagement-bait phrasing before Signal-to-Fix intake."},{"keywords":"AI coding agent bug reports","before":"AI coding agent bug reports airdrop low quality shill","after_shape":"AI coding agent bug reports -airdrop -\"low quality\" -shill min_faves:10","expected_noise_reduction":"removes crypto promo and low-quality spam markers."},{"keywords":"Japan SaaS onboarding complaints","before":"Japan SaaS onboarding complaints what do you think free mint","after_shape":"Japan SaaS onboarding complaints -\"what do you think\" -\"free mint\" lang:en","expected_noise_reduction":"keeps product complaint intent while dropping bait terms."}],"quantitative_noise_examples":[{"keywords":"frontier AI","evidence_type":"synthetic_calibration_example","before":{"raw_search_sample":"frontier AI game changer airdrop what do you think free mint","illustrative_spam_share":"40%","illustrative_engagement_bait_share":"35%"},"after":{"preset":"medium","removed_terms":["airdrop","free mint","game changer","what do you think"],"illustrative_spam_remaining":"8%","illustrative_engagement_bait_remaining":"12%"},"illustrative_reduction":{"spam":"80%","engagement_bait":"66%"}},{"keywords":"open source CRM feedback","evidence_type":"synthetic_calibration_example","before":{"raw_search_sample":"open source CRM feedback giveaway retweet to win thoughts?","illustrative_spam_share":"30%","illustrative_engagement_bait_share":"45%"},"after":{"preset":"medium","removed_terms":["giveaway","retweet to win","thoughts?"],"illustrative_spam_remaining":"7%","illustrative_engagement_bait_remaining":"16%"},"illustrative_reduction":{"spam":"77%","engagement_bait":"64%"}},{"keywords":"AI coding agent bug reports","evidence_type":"synthetic_calibration_example","before":{"raw_search_sample":"AI coding agent bug reports airdrop low quality shill","illustrative_spam_share":"35%","illustrative_engagement_bait_share":"20%"},"after":{"preset":"high","removed_terms":["airdrop","low quality","shill"],"illustrative_spam_remaining":"4%","illustrative_engagement_bait_remaining":"10%"},"illustrative_reduction":{"spam":"89%","engagement_bait":"50%"}},{"keywords":"Japan SaaS onboarding complaints","evidence_type":"synthetic_calibration_example","before":{"raw_search_sample":"Japan SaaS onboarding complaints what do you think free mint","illustrative_spam_share":"25%","illustrative_engagement_bait_share":"30%"},"after":{"preset":"medium","removed_terms":["what do you think","free mint"],"illustrative_spam_remaining":"6%","illustrative_engagement_bait_remaining":"11%"},"illustrative_reduction":{"spam":"76%","engagement_bait":"63%"}}],"preset_comparison":[{"preset":"low","average_spam_reduction":"illustrative 45%","average_engagement_bait_reduction":"illustrative 20%","best_for":"broad discovery"},{"preset":"medium","average_spam_reduction":"illustrative 78%","average_engagement_bait_reduction":"illustrative 65%","best_for":"agent feedback sourcing"},{"preset":"high","average_spam_reduction":"illustrative 88%","average_engagement_bait_reduction":"illustrative 74%","best_for":"high-precision research"}],"evidence_note":"Noise reduction percentages are synthetic calibration examples, not production measurement claims.","integration_examples":{"javascript":"const preview = await fetch('/hyperxosist-query-dry-run').then(r => r.json());","typescript":"type HyperXosistInput = { keywords: string; lang?: string; noise?: { enabled: boolean; preset?: 'low' | 'medium' | 'high' } }; const res = await fetch(base + '/hyperxosist-query-dry-run', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ keywords: 'frontier AI', lang: 'en', noise: { enabled: true, preset: 'medium' } } satisfies HyperXosistInput) });"},"limitations_and_sla":{"dry_run_price":"free","dry_run_availability":"best-effort public endpoint, intended to remain free","paid_query_target_uptime":"99%","paid_query_target_unpaid_response_ms":1000,"note":"SLA-style targets are operational goals, not a legal service-level agreement."},"version_info":{"service_version":"2026-05-25-d1-revenue-log","api_version":"2026-07-agent-conversion","changelog":"/proof.md","changelog_url":"/proof.md"},"recommended_entrypoints":["/agent.json","/payment-options.json","/goal","/openapi.json","/pricing.json","/buy"],"use_cases":["command failure triage","public URL summary","shell safety precheck","agent discovery visibility audit","paid X search query generation"],"first_read_order":["/agent.json","/capabilities.json","/hyperxosist-query-dry-run","/x402-payment.json","/payment-options.json","/.well-known/x402/discovery/resources"]}