{"openapi":"3.1.0","info":{"title":"KG-NINJA x402 Agent API","version":"2.6.0","x-service-version":"2026-05-25-d1-revenue-log","x-release-date":"2026-07-21","x-schema-version":2,"description":"Machine-payable agent API with free discovery and preview tools, plus x402-paid execution endpoints for structured agent results."},"servers":[{"url":"/","description":"Current request origin (api.kgninja.dev in production)."}],"x-mcp":{"endpoint":"https://mcp.kgninja.dev/mcp","health":"https://mcp.kgninja.dev/health","transport":"streamable-http","access_tier":"free","tools":["hyperxosist_search_plan","hyperxosist_filter_signals","hyperxosist_build_handoff"]},"x-service-tiers":{"free":[{"endpoint":"/find","methods":["GET"],"purpose":"Human goal matching and opt-in subscriptions."},{"endpoint":"/catalog.json","methods":["GET"],"purpose":"Existing offer catalog with limits and free alternatives."},{"endpoint":"/match","methods":["POST"],"purpose":"Match goals, budgets and networks without payment authorization."},{"endpoint":"/offers.json","methods":["GET"],"purpose":"Opt-in JSON feed of offer revision announcements."},{"endpoint":"/offers.xml","methods":["GET"],"purpose":"Opt-in RSS feed of offer revision announcements."},{"endpoint":"/fix-error/preview","methods":["GET"],"purpose":"Preview the repair receipt schema and examples without payment."},{"endpoint":"/hyperxosist-query-dry-run","methods":["GET","POST"],"purpose":"Preview HyperXosist search policy and output shape without payment."},{"endpoint":"https://mcp.kgninja.dev/mcp","methods":["POST"],"purpose":"Remote MCP discovery, planning, filtering, and handoff."}],"paid":[{"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}]},"x-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."]},"x-payment":{"protocol":"x402","network":"eip155:8453","asset":"USDC","price":"$0.01","payment_options_url":"/payment-options.json","payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"]},"x402":{"protocol":"x402","protocol_reference":"https://x402.org","version":2,"version_type":"number","version_required":true,"scheme":"exact","network":"eip155:8453","currency":"USDC","price":"$0.01","payTo":"0x4D7d842536De9Eb491AE2300126B3CDdE7B0aDE3","accepted_headers":["X-PAYMENT","PAYMENT","PAYMENT-SIGNATURE"],"payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"],"payment_options_url":"/payment-options.json","discovery_resources_url":"/.well-known/x402/discovery/resources","canonical_openapi_url":"/openapi.json","bazaar_indexing":{"x402Version":2,"version_type":"number","version_required":true,"scheme":"exact","network":"eip155:8453","asset":"USDC","asset_contract":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","resource_identity":"absolute_resource_url","resource_url_rule":"Each paid route advertises and challenges against its own absolute HTTPS resource URL.","facilitator":"cdp","facilitator_url":"https://api.cdp.coinbase.com/platform/v2/x402","cdp_facilitator_configured":true,"cdp_credentials_present":true,"bazaar_extension_status":"declared_on_paid_routes","bazaar_extension_note":"Each paid POST route declares a v2 Bazaar discovery extension through the installed x402 SDK. Listing still depends on facilitator settlement and external indexing.","indexing_expectation":"Bazaar visibility should be treated as route/resource-level and settlement-gated until Coinbase confirms otherwise.","debug_signals":{"payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"],"extension_response_header":"EXTENSION-RESPONSES","local_integrity_endpoint":"/revenue-log/integrity"}},"expected_unpaid_response":402,"expected_paid_response":200},"components":{"schemas":{"PaymentRequired":{"type":"object","required":["status","x402Version","resource","price","asset","network","payTo","payment_options","payment_required"],"properties":{"status":{"const":"payment_required"},"x402Version":{"const":2},"resource":{"type":"string"},"price":{"type":"string"},"asset":{"const":"USDC"},"network":{"type":"string"},"payTo":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"payment_metadata":{"type":"string"},"payment_options":{"type":"string"},"payment_required":{"type":["object","null"],"description":"The same x402 v2 challenge carried in the PAYMENT-REQUIRED header, provided for body-reading clients.","properties":{"x402Version":{"const":2},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}}},"additionalProperties":true}},"additionalProperties":false},"AgentError":{"type":"object","properties":{"status":{"type":["integer","string"]},"error":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"next_action":{"type":"string"}},"additionalProperties":true},"FixErrorReceipt":{"type":"object","additionalProperties":false,"required":["status","service","version","mode","network","real_revenue","input_received","request_id","revenue_proof_log","durable_revenue_log","post_payment_retry_path","receipt"],"properties":{"status":{"type":"string","enum":["paid"]},"service":{"type":"string"},"version":{"type":"string"},"mode":{"type":"string"},"network":{"type":"string"},"real_revenue":{"type":"boolean","description":"Server mainnet configuration flag; not independent evidence of customer revenue."},"input_received":{"type":"boolean"},"request_id":{"type":"string"},"revenue_proof_log":{"type":"string"},"durable_revenue_log":{"type":"boolean"},"post_payment_retry_path":{"type":"string"},"receipt":{"type":"object","additionalProperties":false,"required":["root_cause","next_command","retry_plan","risk_note","prevention_note","generated_at"],"properties":{"root_cause":{"type":"string","description":"Concise diagnosis based on the submitted evidence."},"next_command":{"type":"string","description":"One concrete command or action to try next."},"retry_plan":{"type":"array","items":{"type":"string"},"description":"Ordered recovery steps, including when to submit a new error."},"risk_note":{"type":"string","description":"Operational or security caution for the proposed action."},"prevention_note":{"type":"string","description":"A preventive practice for future runs."},"generated_at":{"type":"string","format":"date-time","description":"Receipt generation timestamp."}}}}},"SummarizeUrl":{"type":"object","required":["status","summary","title","url"],"properties":{"status":{"const":"paid"},"summary":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"}},"additionalProperties":false},"ShellRiskAssessment":{"type":"object","required":["status","risk_level","explanation","safer_alternative"],"properties":{"status":{"const":"paid"},"risk_level":{"type":"string","enum":["low","medium","high","critical"]},"explanation":{"type":"string"},"safer_alternative":{"type":"string"}},"additionalProperties":false},"HyperXosistQueryResult":{"type":"object","required":["status","service","query","searchUrl","mode","appliedNoiseTerms","excludeTerms","generated_at","version","payment"],"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"},"version":{"type":"string"},"payment":{"type":"object","required":["protocol","paid","price","network","real_revenue"],"properties":{"protocol":{"const":"x402"},"paid":{"type":"boolean"},"demo":{"type":"boolean"},"bypass":{"type":"string"},"price":{"type":"string"},"network":{"type":"string"},"real_revenue":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false},"FreeFixErrorPreview":{"type":"object","required":["service","version","price","payment","network","paid_endpoint","output_schema","expected_output_schema"],"properties":{"service":{"type":"string"},"version":{"type":"string"},"mode":{"type":"string"},"price":{"type":"string"},"payment":{"const":"x402"},"network":{"type":"string"},"paid_endpoint":{"type":"string"},"output_schema":{"type":"object"},"expected_output_schema":{"type":"object"}},"additionalProperties":true},"HyperXosistDryRunPreview":{"type":"object","required":["status","service","free","paid_execution_required","paid_endpoint","payment","json_schema","preview","version_info"],"properties":{"status":{"const":"dry_run"},"service":{"type":"string"},"free":{"const":true},"paid_execution_required":{"const":true},"paid_endpoint":{"type":"string"},"payment":{"type":"object"},"json_schema":{"type":"object"},"preview":{"type":"object"},"version_info":{"type":"object"}},"additionalProperties":true}},"headers":{"PaymentRequired":{"description":"Base64-encoded JSON x402 v2 payment challenge returned with HTTP 402.","schema":{"type":"string","contentEncoding":"base64"}},"PaymentResponse":{"description":"x402 settlement response header returned after successful payment verification.","schema":{"type":"string"}}}},"paths":{"/find":{"get":{"x-access-tier":"free","security":[],"operationId":"findHumanOffer","summary":"Human goal matching and opt-in subscriptions","responses":{"200":{"description":"HTML matching form","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/catalog.json":{"get":{"x-access-tier":"free","security":[],"operationId":"getOfferCatalog","summary":"Current offer prices, limitations, examples and subscription links","responses":{"200":{"description":"Seller-supplied catalog; no payment authorization","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/match":{"post":{"x-access-tier":"free","security":[],"operationId":"matchGoalToOffers","summary":"Match a goal, per-request budget and network without making a purchase","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"need":{"type":"string","minLength":1,"maxLength":500},"intent":{"type":"string","enum":["command-error","url-summary","shell-safety","service-visibility","x-search"]},"max_price_usdc":{"type":"string","pattern":"^(?:0|[1-9][0-9]{0,8})(?:\\.[0-9]{1,6})?$"},"network":{"type":"string","pattern":"^eip155:[0-9]{1,12}$"},"prefer_free":{"type":"boolean"},"local_solution_sufficient":{"type":"boolean"}},"oneOf":[{"required":["need"],"not":{"required":["intent"]}},{"required":["intent"],"not":{"required":["need"]}}]}}}},"responses":{"200":{"description":"Seller-supplied candidates selected by explicit intent or conservative keyword matching; skip when constraints fail. No purchase or authorization.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["schema_version","decision","reason","matches","free_options","purchase_executed","payment_authorized","policy"],"properties":{"schema_version":{"const":"1.0"},"decision":{"enum":["review","skip"]},"reason":{"type":"string"},"matches":{"type":"array","maxItems":3,"items":{"type":"object","required":["id","intent","title","description","limitation","url","method","endpoint","price","payment","input_schema","example_request","free_preview","free_alternative","subscription"],"properties":{"id":{"type":"string"},"intent":{"type":"string","enum":["command-error","url-summary","shell-safety","service-visibility","x-search"]},"title":{"type":"string"},"description":{"type":"string"},"limitation":{"type":"string"},"url":{"type":"string"},"method":{"const":"POST"},"endpoint":{"type":"string"},"input_schema":{"type":"string"},"example_request":{"type":"object"},"free_preview":{"type":"string"},"free_alternative":{"type":"string"},"subscription":{"type":"object","required":["json","rss"],"properties":{"json":{"type":"string"},"rss":{"type":"string"}}},"price":{"type":"object","required":["amount","currency","atomic_amount","network","mode"],"properties":{"amount":{"type":"string"},"currency":{"const":"USDC"},"atomic_amount":{"type":["string","null"]},"network":{"type":"string"},"mode":{"type":"string"}}},"payment":{"type":"object","required":["protocol","version","recipient","requirements","authorization_required"],"properties":{"protocol":{"const":"x402"},"version":{"const":2},"recipient":{"type":"string"},"requirements":{"type":"string"},"authorization_required":{"const":true}}}}}},"free_options":{"type":"array","items":{"type":"object","required":["id","title","description","url","subscription"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"subscription":{"type":"object","required":["json","rss"],"properties":{"json":{"type":"string"},"rss":{"type":"string"}}}}}},"purchase_executed":{"const":false},"payment_authorized":{"const":false},"policy":{"type":"string"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object"}}}},"413":{"description":"Body exceeds 8192 bytes","content":{"text/plain":{"schema":{"type":"string"}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/offers.json":{"get":{"x-access-tier":"free","security":[],"operationId":"getOfferRevisionFeed","summary":"Opt-in JSON Feed; poll hourly and deduplicate revision announcements by item.id","parameters":[{"name":"intent","in":"query","required":false,"schema":{"type":"string","enum":["command-error","url-summary","shell-safety","service-visibility","x-search"]}},{"name":"max_price_usdc","in":"query","required":false,"schema":{"type":"string","pattern":"^(?:0|[1-9][0-9]{0,8})(?:\\.[0-9]{1,6})?$"}},{"name":"network","in":"query","required":false,"schema":{"type":"string","pattern":"^eip155:[0-9]{1,12}$"}}],"responses":{"200":{"description":"JSON Feed 1.1 with _kg_offer extension","content":{"application/feed+json":{"schema":{"type":"object"}}}},"304":{"description":"Unchanged ETag"},"400":{"description":"Invalid filters","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/offers.xml":{"get":{"x-access-tier":"free","security":[],"operationId":"getOfferRevisionRss","summary":"Opt-in RSS 2.0 with stable revision GUIDs","parameters":[{"name":"intent","in":"query","required":false,"schema":{"type":"string","enum":["command-error","url-summary","shell-safety","service-visibility","x-search"]}},{"name":"max_price_usdc","in":"query","required":false,"schema":{"type":"string","pattern":"^(?:0|[1-9][0-9]{0,8})(?:\\.[0-9]{1,6})?$"}},{"name":"network","in":"query","required":false,"schema":{"type":"string","pattern":"^eip155:[0-9]{1,12}$"}}],"responses":{"200":{"description":"RSS feed","content":{"application/rss+xml":{"schema":{"type":"string"}}}},"304":{"description":"Unchanged ETag"},"400":{"description":"Invalid filters","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/fix-error/preview":{"get":{"summary":"Free repair receipt preview","operationId":"getFixErrorPreview","description":"Read the free input/output schema and examples before using the paid repair endpoint.","x-access-tier":"free","responses":{"200":{"description":"Free preview: JSON schema for clients or purchase guide for browsers, selected by Accept","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreeFixErrorPreview"}},"text/html":{"schema":{"type":"string"}}}}}}},"/hyperxosist-query-dry-run":{"get":{"summary":"Free HyperXosist search dry-run","operationId":"getHyperXosistQueryDryRun","description":"Preview search policy and output shape without payment. It does not scrape X or return paid execution content.","x-access-tier":"free","responses":{"200":{"description":"Free dry-run metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HyperXosistDryRunPreview"}}}}}},"post":{"summary":"Free HyperXosist search dry-run","operationId":"previewHyperXosistQuery","description":"Preview a generated query shape and noise policy without payment. It does not scrape X or return the paid query result.","x-access-tier":"free","requestBody":{"required":true,"content":{"application/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"]}}}},"responses":{"200":{"description":"Free dry-run metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HyperXosistDryRunPreview"}}}}}}},"/fix-error":{"post":{"summary":"Paid command error repair receipt","operationId":"createFixError","description":"Submit one failing command, error message, log, or environment note. Unpaid requests return 402; retry with x402 payment proof for a 200 JSON receipt.","x-access-tier":"paid","x-payment-info":{"protocol":"x402","protocol_reference":"https://x402.org","version":2,"version_type":"number","version_required":true,"scheme":"exact","network":"eip155:8453","currency":"USDC","price":"$0.01","payTo":"0x4D7d842536De9Eb491AE2300126B3CDdE7B0aDE3","accepted_headers":["X-PAYMENT","PAYMENT","PAYMENT-SIGNATURE"],"payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"],"payment_options_url":"/payment-options.json","discovery_resources_url":"/.well-known/x402/discovery/resources","canonical_openapi_url":"/openapi.json","bazaar_indexing":{"x402Version":2,"version_type":"number","version_required":true,"scheme":"exact","network":"eip155:8453","asset":"USDC","asset_contract":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","resource_identity":"absolute_resource_url","resource_url_rule":"Each paid route advertises and challenges against its own absolute HTTPS resource URL.","facilitator":"cdp","facilitator_url":"https://api.cdp.coinbase.com/platform/v2/x402","cdp_facilitator_configured":true,"cdp_credentials_present":true,"bazaar_extension_status":"declared_on_paid_routes","bazaar_extension_note":"Each paid POST route declares a v2 Bazaar discovery extension through the installed x402 SDK. Listing still depends on facilitator settlement and external indexing.","indexing_expectation":"Bazaar visibility should be treated as route/resource-level and settlement-gated until Coinbase confirms otherwise.","debug_signals":{"payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"],"extension_response_header":"EXTENSION-RESPONSES","local_integrity_endpoint":"/revenue-log/integrity"}},"expected_unpaid_response":402,"expected_paid_response":200},"x-upgrade-guidance":{"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."],"free_alternative":"/fix-error/preview","paid_result":"repair_receipt","retry":"On HTTP 402, obtain x402 payment proof and retry the same POST request."},"x-paid-result":"repair_receipt","x-when-to-use":["A command, build, deployment, API call, or service check failed and the next action is unclear.","A retry produced a new error message or failed at a different stage.","The runtime, dependency version, environment, or deployment target changed.","A concise machine-readable diagnosis is needed before an automation continues."],"x-repeat-use-scenarios":["Submit the new error after applying the previous receipt's next command.","Submit the same workflow failure after changing dependencies, runtime, or environment.","Submit each distinct failure stage in a build or deployment as a separate diagnosis.","Use a new request when fresh logs contain evidence not present in the previous request.","Do not repeat an unchanged request unless the execution context changed."],"x-what-you-receive-after-payment":{"result":"One JSON repair receipt for the submitted failure.","includes":["root_cause","next_command","retry_plan","risk_note","prevention_note","generated_at"],"delivery":"The paid retry returns HTTP 200. Read diagnostic fields from response.receipt, for example response.receipt.root_cause.","continuation":"Apply the guidance, then submit only a new or materially changed error as another /fix-error request."},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"command":{"type":"string"},"error":{"type":"string"},"log":{"type":"string"},"environment":{"type":"string"}},"additionalProperties":false},"example":{"command":"npm run build","error":"Error: Cannot find module 'hono'","environment":"Node.js Cloudflare Worker build"},"examples":{"missing_dependency":{"summary":"Build fails because a dependency cannot be resolved","value":{"command":"npm run build","error":"Error: Cannot find module 'hono'","environment":"Node.js Cloudflare Worker build"}},"invalid_deployment_credential":{"summary":"Deployment fails with an authorization error","value":{"command":"npm run deploy","error":"401 Unauthorized: API token invalid","environment":"CI deployment"}},"unavailable_local_service":{"summary":"A local health check cannot reach the service","value":{"command":"curl http://127.0.0.1:3000/health","error":"Connection refused","environment":"Linux service"}}}}}},"responses":{"200":{"description":"Paid JSON response","headers":{"PAYMENT-RESPONSE":{"$ref":"#/components/headers/PaymentResponse"},"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/PaymentResponse"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["status","service","version","mode","network","real_revenue","input_received","request_id","revenue_proof_log","durable_revenue_log","post_payment_retry_path","receipt"],"properties":{"status":{"type":"string","enum":["paid"]},"service":{"type":"string"},"version":{"type":"string"},"mode":{"type":"string"},"network":{"type":"string"},"real_revenue":{"type":"boolean","description":"Server mainnet configuration flag; not independent evidence of customer revenue."},"input_received":{"type":"boolean"},"request_id":{"type":"string"},"revenue_proof_log":{"type":"string"},"durable_revenue_log":{"type":"boolean"},"post_payment_retry_path":{"type":"string"},"receipt":{"type":"object","additionalProperties":false,"required":["root_cause","next_command","retry_plan","risk_note","prevention_note","generated_at"],"properties":{"root_cause":{"type":"string","description":"Concise diagnosis based on the submitted evidence."},"next_command":{"type":"string","description":"One concrete command or action to try next."},"retry_plan":{"type":"array","items":{"type":"string"},"description":"Ordered recovery steps, including when to submit a new error."},"risk_note":{"type":"string","description":"Operational or security caution for the proposed action."},"prevention_note":{"type":"string","description":"A preventive practice for future runs."},"generated_at":{"type":"string","format":"date-time","description":"Receipt generation timestamp."}}}}},"example":{"status":"paid","service":"Agent Error Fix Receipt","version":"2026-05-25-d1-revenue-log","mode":"mainnet","network":"eip155:8453","real_revenue":true,"input_received":true,"request_id":"example-request-id","revenue_proof_log":"paid_fix_error_receipt_issued","durable_revenue_log":true,"post_payment_retry_path":"Retry POST /fix-error with x402 payment proof.","receipt":{"root_cause":"The failure appears related to a missing package, missing file, or unresolved module path.","next_command":"npm install","retry_plan":["Confirm the exact failing command.","Run the smallest non-destructive diagnostic command relevant to the error.","Check whether required environment variables, packages, files, or services are present.","Retry the original command once after the minimal fix."],"risk_note":"Do not run destructive cleanup, reset, rm, database, credential, or firewall commands without manual review.","prevention_note":"Store this error pattern in a runbook and add a preflight check before future runs.","generated_at":"2026-06-14T00:00:00.000Z"}}}}},"402":{"description":"Payment Required via x402","headers":{"PAYMENT-REQUIRED":{"$ref":"#/components/headers/PaymentRequired"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"default":{"description":"Unexpected validation or server error. Inspect error and retryable fields before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}},"head":{"operationId":"headFixErrorRoute","responses":{"200":{"description":"Route exists"}}},"options":{"operationId":"optionsFixErrorRoute","responses":{"204":{"description":"CORS preflight"}}}},"/summarize-url":{"post":{"summary":"Paid URL title and short summary","operationId":"summarizePublicUrl","description":"Return a compact title and summary for a public URL. No free route is defined for this paid operation.","x-access-tier":"paid","x-payment-info":{"protocol":"x402","protocol_reference":"https://x402.org","version":2,"version_type":"number","version_required":true,"scheme":"exact","network":"eip155:8453","currency":"USDC","price":"$0.01","payTo":"0x4D7d842536De9Eb491AE2300126B3CDdE7B0aDE3","accepted_headers":["X-PAYMENT","PAYMENT","PAYMENT-SIGNATURE"],"payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"],"payment_options_url":"/payment-options.json","discovery_resources_url":"/.well-known/x402/discovery/resources","canonical_openapi_url":"/openapi.json","bazaar_indexing":{"x402Version":2,"version_type":"number","version_required":true,"scheme":"exact","network":"eip155:8453","asset":"USDC","asset_contract":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","resource_identity":"absolute_resource_url","resource_url_rule":"Each paid route advertises and challenges against its own absolute HTTPS resource URL.","facilitator":"cdp","facilitator_url":"https://api.cdp.coinbase.com/platform/v2/x402","cdp_facilitator_configured":true,"cdp_credentials_present":true,"bazaar_extension_status":"declared_on_paid_routes","bazaar_extension_note":"Each paid POST route declares a v2 Bazaar discovery extension through the installed x402 SDK. Listing still depends on facilitator settlement and external indexing.","indexing_expectation":"Bazaar visibility should be treated as route/resource-level and settlement-gated until Coinbase confirms otherwise.","debug_signals":{"payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"],"extension_response_header":"EXTENSION-RESPONSES","local_integrity_endpoint":"/revenue-log/integrity"}},"expected_unpaid_response":402,"expected_paid_response":200},"x-upgrade-guidance":{"required_when":["The client requests a title and short summary for a public URL."],"not_required_when":["The client is only discovering the schema."],"free_alternative":null,"paid_result":"url_summary","retry":"On HTTP 402, obtain x402 payment proof and retry the same POST request."},"x-paid-result":"url_summary","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Paid URL summary JSON","headers":{"PAYMENT-RESPONSE":{"$ref":"#/components/headers/PaymentResponse"},"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/PaymentResponse"}},"content":{"application/json":{"schema":{"type":"object","required":["status","summary","title","url"],"properties":{"status":{"const":"paid"},"summary":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"}},"additionalProperties":false}}}},"402":{"description":"Payment Required via x402","headers":{"PAYMENT-REQUIRED":{"$ref":"#/components/headers/PaymentRequired"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"default":{"description":"Unexpected validation or server error. Inspect error and retryable fields before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}},"head":{"operationId":"headSummarizeUrlRoute","responses":{"200":{"description":"Route exists"}}},"options":{"operationId":"optionsSummarizeUrlRoute","responses":{"204":{"description":"CORS preflight"}}}},"/shell-risk-check":{"post":{"summary":"Paid deterministic shell command risk check","operationId":"checkShellCommandRisk","description":"Classify shell command risk before execution. No free route is defined for this paid operation.","x-access-tier":"paid","x-payment-info":{"protocol":"x402","protocol_reference":"https://x402.org","version":2,"version_type":"number","version_required":true,"scheme":"exact","network":"eip155:8453","currency":"USDC","price":"$0.01","payTo":"0x4D7d842536De9Eb491AE2300126B3CDdE7B0aDE3","accepted_headers":["X-PAYMENT","PAYMENT","PAYMENT-SIGNATURE"],"payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"],"payment_options_url":"/payment-options.json","discovery_resources_url":"/.well-known/x402/discovery/resources","canonical_openapi_url":"/openapi.json","bazaar_indexing":{"x402Version":2,"version_type":"number","version_required":true,"scheme":"exact","network":"eip155:8453","asset":"USDC","asset_contract":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","resource_identity":"absolute_resource_url","resource_url_rule":"Each paid route advertises and challenges against its own absolute HTTPS resource URL.","facilitator":"cdp","facilitator_url":"https://api.cdp.coinbase.com/platform/v2/x402","cdp_facilitator_configured":true,"cdp_credentials_present":true,"bazaar_extension_status":"declared_on_paid_routes","bazaar_extension_note":"Each paid POST route declares a v2 Bazaar discovery extension through the installed x402 SDK. Listing still depends on facilitator settlement and external indexing.","indexing_expectation":"Bazaar visibility should be treated as route/resource-level and settlement-gated until Coinbase confirms otherwise.","debug_signals":{"payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"],"extension_response_header":"EXTENSION-RESPONSES","local_integrity_endpoint":"/revenue-log/integrity"}},"expected_unpaid_response":402,"expected_paid_response":200},"x-upgrade-guidance":{"required_when":["The client requests a shell risk assessment for a command."],"not_required_when":["The client is only discovering the schema."],"free_alternative":null,"paid_result":"shell_risk_assessment","retry":"On HTTP 402, obtain x402 payment proof and retry the same POST request."},"x-paid-result":"shell_risk_assessment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["command"],"properties":{"command":{"type":"string"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Paid shell risk assessment JSON","headers":{"PAYMENT-RESPONSE":{"$ref":"#/components/headers/PaymentResponse"},"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/PaymentResponse"}},"content":{"application/json":{"schema":{"type":"object","required":["status","risk_level","explanation","safer_alternative"],"properties":{"status":{"const":"paid"},"risk_level":{"type":"string","enum":["low","medium","high","critical"]},"explanation":{"type":"string"},"safer_alternative":{"type":"string"}},"additionalProperties":false}}}},"402":{"description":"Payment Required via x402","headers":{"PAYMENT-REQUIRED":{"$ref":"#/components/headers/PaymentRequired"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"default":{"description":"Unexpected validation or server error. Inspect error and retryable fields before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}},"head":{"operationId":"headShellRiskCheckRoute","responses":{"200":{"description":"Route exists"}}},"options":{"operationId":"optionsShellRiskCheckRoute","responses":{"204":{"description":"CORS preflight"}}}},"/agent-visibility-report":{"post":{"summary":"Paid aggregate agent visibility report","operationId":"createAgentVisibilityReport","description":"Generate a privacy-safe aggregate report of machine discovery, x402 payment readiness, and recommended next fix. Uses only aggregate telemetry.","x-access-tier":"paid","x-payment-info":{"protocol":"x402","protocol_reference":"https://x402.org","version":2,"version_type":"number","version_required":true,"scheme":"exact","network":"eip155:8453","currency":"USDC","price":"$0.01","payTo":"0x4D7d842536De9Eb491AE2300126B3CDdE7B0aDE3","accepted_headers":["X-PAYMENT","PAYMENT","PAYMENT-SIGNATURE"],"payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"],"payment_options_url":"/payment-options.json","discovery_resources_url":"/.well-known/x402/discovery/resources","canonical_openapi_url":"/openapi.json","bazaar_indexing":{"x402Version":2,"version_type":"number","version_required":true,"scheme":"exact","network":"eip155:8453","asset":"USDC","asset_contract":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","resource_identity":"absolute_resource_url","resource_url_rule":"Each paid route advertises and challenges against its own absolute HTTPS resource URL.","facilitator":"cdp","facilitator_url":"https://api.cdp.coinbase.com/platform/v2/x402","cdp_facilitator_configured":true,"cdp_credentials_present":true,"bazaar_extension_status":"declared_on_paid_routes","bazaar_extension_note":"Each paid POST route declares a v2 Bazaar discovery extension through the installed x402 SDK. Listing still depends on facilitator settlement and external indexing.","indexing_expectation":"Bazaar visibility should be treated as route/resource-level and settlement-gated until Coinbase confirms otherwise.","debug_signals":{"payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"],"extension_response_header":"EXTENSION-RESPONSES","local_integrity_endpoint":"/revenue-log/integrity"}},"expected_unpaid_response":402,"expected_paid_response":200},"x-upgrade-guidance":{"required_when":["The client requests the aggregate visibility report."],"not_required_when":["The client is only discovering the schema."],"free_alternative":null,"paid_result":"privacy_safe_agent_visibility_report","retry":"On HTTP 402, obtain x402 payment proof and retry the same POST request."},"x-paid-result":"privacy_safe_agent_visibility_report","x-privacy-guarantee":{"raw_ip_exposed":false,"raw_user_agent_exposed":false,"wallet_addresses_exposed":false,"event_level_logs_exposed":false,"aggregation_only":true},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"target_url":{"type":"string","format":"uri"},"mode":{"type":"string"}},"additionalProperties":false},"example":{"target_url":"https://agentos-revenue-cloudflare.fuwafuwow.workers.dev","mode":"standard"}}}},"responses":{"200":{"description":"Privacy-safe aggregate report JSON","headers":{"PAYMENT-RESPONSE":{"$ref":"#/components/headers/PaymentResponse"},"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/PaymentResponse"}},"content":{"application/json":{"schema":{"type":"object","required":["report_type","generated_at","agent_visibility_score","payment_readiness_score","machine_discovery_score","detected_gaps","matched_real_world_patterns","recommended_next_fix","privacy"],"properties":{"report_type":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"agent_visibility_score":{"type":"number"},"payment_readiness_score":{"type":"number"},"machine_discovery_score":{"type":"number"},"detected_gaps":{"type":"array","items":{"type":"string"}},"matched_real_world_patterns":{"type":"array","items":{"type":"string"}},"recommended_next_fix":{"type":"object"},"privacy":{"type":"object"}}},"example":{"report_type":"agent_visibility_report","agent_visibility_score":80,"payment_readiness_score":45,"machine_discovery_score":88,"detected_gaps":["Payment value proposition is not explicit enough in discovery metadata"],"matched_real_world_patterns":["Machine clients commonly inspect /openapi.json before paid endpoint access"],"recommended_next_fix":{"priority":"high","action":"Make paid result fields explicit in discovery metadata"},"privacy":{"raw_ip_exposed":false,"raw_user_agent_exposed":false,"wallet_addresses_exposed":false,"event_level_logs_exposed":false,"aggregation_only":true}}}}},"402":{"description":"Payment Required via x402","headers":{"PAYMENT-REQUIRED":{"$ref":"#/components/headers/PaymentRequired"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"},"example":{"error":"Payment Required","service":"Agent Visibility Report","why_pay":"Payment unlocks a privacy-safe aggregate report.","paid_result_includes":["agent_visibility_score","payment_readiness_score","machine_discovery_score","detected_metadata_gaps","matched_real_world_discovery_patterns","recommended_next_fix","privacy_safe_aggregate_signals"],"privacy_guarantee":{"raw_ip_exposed":false,"raw_user_agent_exposed":false,"wallet_addresses_exposed":false,"event_level_logs_exposed":false,"aggregation_only":true}}}}},"default":{"description":"Unexpected validation or server error. Inspect error and retryable fields before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}},"head":{"operationId":"headAgentVisibilityReportRoute","responses":{"200":{"description":"Route exists"}}},"options":{"operationId":"optionsAgentVisibilityReportRoute","responses":{"204":{"description":"CORS preflight"}}}},"/hyperxosist-query":{"post":{"summary":"Paid HyperXosist query and official X search URL","operationId":"createHyperXosistQuery","description":"Generate a noise-reduced query and official X search URL for automated production use. This endpoint does not directly scrape X. Unpaid requests return 402; retry with x402 payment proof for 200.","x-access-tier":"paid","x-payment-info":{"protocol":"x402","protocol_reference":"https://x402.org","version":2,"version_type":"number","version_required":true,"scheme":"exact","network":"eip155:8453","currency":"USDC","price":"$0.01","payTo":"0x4D7d842536De9Eb491AE2300126B3CDdE7B0aDE3","accepted_headers":["X-PAYMENT","PAYMENT","PAYMENT-SIGNATURE"],"payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"],"payment_options_url":"/payment-options.json","discovery_resources_url":"/.well-known/x402/discovery/resources","canonical_openapi_url":"/openapi.json","bazaar_indexing":{"x402Version":2,"version_type":"number","version_required":true,"scheme":"exact","network":"eip155:8453","asset":"USDC","asset_contract":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","resource_identity":"absolute_resource_url","resource_url_rule":"Each paid route advertises and challenges against its own absolute HTTPS resource URL.","facilitator":"cdp","facilitator_url":"https://api.cdp.coinbase.com/platform/v2/x402","cdp_facilitator_configured":true,"cdp_credentials_present":true,"bazaar_extension_status":"declared_on_paid_routes","bazaar_extension_note":"Each paid POST route declares a v2 Bazaar discovery extension through the installed x402 SDK. Listing still depends on facilitator settlement and external indexing.","indexing_expectation":"Bazaar visibility should be treated as route/resource-level and settlement-gated until Coinbase confirms otherwise.","debug_signals":{"payment_required_header":"PAYMENT-REQUIRED","settlement_headers":["PAYMENT-RESPONSE","X-PAYMENT-RESPONSE"],"extension_response_header":"EXTENSION-RESPONSES","local_integrity_endpoint":"/revenue-log/integrity"}},"expected_unpaid_response":402,"expected_paid_response":200},"x-upgrade-guidance":{"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."],"free_alternative":"/hyperxosist-query-dry-run","paid_result":"hyperxosist_search_query_and_url","retry":"On HTTP 402, obtain x402 payment proof and retry the same POST request."},"x-paid-result":"hyperxosist_search_query_and_url","requestBody":{"required":true,"content":{"application/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"]}}}},"responses":{"200":{"description":"Paid HyperXosist query JSON","headers":{"PAYMENT-RESPONSE":{"$ref":"#/components/headers/PaymentResponse"},"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/PaymentResponse"}},"content":{"application/json":{"schema":{"type":"object","required":["status","service","query","searchUrl","mode","appliedNoiseTerms","excludeTerms","generated_at","version","payment"],"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"},"version":{"type":"string"},"payment":{"type":"object","required":["protocol","paid","price","network","real_revenue"],"properties":{"protocol":{"const":"x402"},"paid":{"type":"boolean"},"demo":{"type":"boolean"},"bypass":{"type":"string"},"price":{"type":"string"},"network":{"type":"string"},"real_revenue":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"402":{"description":"Payment Required via x402","headers":{"PAYMENT-REQUIRED":{"$ref":"#/components/headers/PaymentRequired"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"default":{"description":"Unexpected validation or server error. Inspect error and retryable fields before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}},"head":{"operationId":"headHyperXosistQueryRoute","responses":{"200":{"description":"Route exists"}}},"options":{"operationId":"optionsHyperXosistQueryRoute","responses":{"204":{"description":"CORS preflight"}}}}}}