{
    "openapi": "3.0.3",
    "info": {
        "title": "Ai for 500 Market Intelligence API",
        "version": "4.1.3",
        "description": "Machine-facing market intelligence for the emerging AI-agent economy. The primary product is Market Check: submit one market, business idea, or commercial opportunity and receive one evidence-backed assessment for $0.05 USDC through x402. No account or subscription is required. Observed facts, derived metrics, and Scout inference are kept separate. Coverage reflects evidence currently tracked by Ai for 500 and should not be interpreted as the entire market."
    },
    "servers": [
        {
            "url": "https://aifor500.com",
            "description": "Production server"
        }
    ],
    "externalDocs": {
        "description": "Agent-readable service information",
        "url": "https://aifor500.com/llms.txt"
    },
    "tags": [
        {
            "name": "Market Intelligence",
            "description": "Paid evidence-backed market assessments for AI agents and builders."
        },
        {
            "name": "Service Metadata",
            "description": "Machine-readable information about Ai for 500."
        }
    ],
    "paths": {
        "/api/": {
            "get": {
                "tags": [
                    "Service Metadata"
                ],
                "operationId": "getServiceMetadata",
                "summary": "Get service metadata",
                "responses": {
                    "200": {
                        "description": "Service metadata returned successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/market-check.php": {
            "post": {
                "tags": [
                    "Market Intelligence"
                ],
                "operationId": "marketCheck",
                "summary": "Evaluate one market or business opportunity",
                "description": "Ai for 500 Market Check costs $0.05 USDC per request through x402. Submit one question about one market, business idea, or commercial opportunity. The optional category may be supplied when already known; otherwise Ai for 500 uses a deterministic keyword classifier. Before payment is settled, the server confirms that a current assessment exists and assembles the intelligence response. An unpaid request returns HTTP 402 with a PAYMENT-REQUIRED header. An x402-capable client signs the required payment, retries the same POST with PAYMENT-SIGNATURE, and receives the paid response plus PAYMENT-RESPONSE after settlement.",
                "parameters": [
                    {
                        "name": "PAYMENT-SIGNATURE",
                        "in": "header",
                        "required": false,
                        "description": "Base64-encoded x402 payment payload. Omit on the initial request to receive the HTTP 402 payment requirements.",
                        "schema": {
                            "type": "string",
                            "maxLength": 16384
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MarketCheckRequest"
                            },
                            "examples": {
                                "monitoring": {
                                    "summary": "Caller supplies the category",
                                    "value": {
                                        "question": "Should I build an x402 URL monitoring service?",
                                        "category": "MONITORING"
                                    }
                                },
                                "automatic_category": {
                                    "summary": "Let Ai for 500 classify the request",
                                    "value": {
                                        "question": "Is AI document extraction worth entering?"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Payment settled and complete Market Check returned",
                        "headers": {
                            "PAYMENT-RESPONSE": {
                                "description": "Base64-encoded x402 settlement response.",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MarketCheckResponse"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Payment is required, invalid, could not be verified, or could not be settled.",
                        "headers": {
                            "PAYMENT-REQUIRED": {
                                "description": "Base64-encoded x402 Version 2 payment requirements. Present on the initial unpaid challenge.",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiError"
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Only POST is accepted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiError"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "No current intelligence assessment exists for the resolved category",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiError"
                                },
                                "example": {
                                    "success": false,
                                    "error": "insufficient_intelligence",
                                    "message": "Ai for 500 does not currently have a market assessment for this category."
                                }
                            }
                        }
                    },
                    "415": {
                        "description": "Content type must be application/json",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiError"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Question or category failed validation",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiError"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Unexpected server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiError"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "MarketCategory": {
                "type": "string",
                "enum": [
                    "SEARCH",
                    "DATA",
                    "VERIFICATION",
                    "MONITORING",
                    "FINANCE",
                    "CRYPTO",
                    "AI_MODELS",
                    "COMMUNICATION",
                    "COMPUTE",
                    "DOCUMENTS",
                    "BUSINESS",
                    "OTHER"
                ]
            },
            "MarketCheckRequest": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "question"
                ],
                "properties": {
                    "question": {
                        "type": "string",
                        "minLength": 3,
                        "maxLength": 1000,
                        "description": "One market, business idea, or commercial opportunity for Ai for 500 to evaluate."
                    },
                    "category": {
                        "$ref": "#/components/schemas/MarketCategory"
                    }
                }
            },
            "CategoryResolution": {
                "type": "object",
                "required": [
                    "method",
                    "classifier_score",
                    "matched_terms"
                ],
                "properties": {
                    "method": {
                        "type": "string",
                        "enum": [
                            "caller_supplied",
                            "deterministic_keyword_classifier"
                        ]
                    },
                    "classifier_score": {
                        "type": "integer",
                        "nullable": true,
                        "minimum": 0
                    },
                    "matched_terms": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                }
            },
            "MarketCheckResolvedRequest": {
                "type": "object",
                "required": [
                    "question",
                    "category",
                    "category_resolution"
                ],
                "properties": {
                    "question": {
                        "type": "string"
                    },
                    "category": {
                        "$ref": "#/components/schemas/MarketCategory"
                    },
                    "category_resolution": {
                        "$ref": "#/components/schemas/CategoryResolution"
                    }
                }
            },
            "Assessment": {
                "type": "object",
                "required": [
                    "label",
                    "decision_score",
                    "decision_score_scale",
                    "confidence",
                    "confidence_meaning",
                    "statement",
                    "reasoning_summary",
                    "flags",
                    "method_version",
                    "generated_at",
                    "valid_until"
                ],
                "properties": {
                    "label": {
                        "type": "string",
                        "enum": [
                            "GAP",
                            "PROMISING",
                            "WATCH",
                            "CONCENTRATED",
                            "CROWDED",
                            "WEAK EVIDENCE"
                        ]
                    },
                    "decision_score": {
                        "type": "integer",
                        "nullable": true,
                        "minimum": 0,
                        "maximum": 100
                    },
                    "decision_score_scale": {
                        "type": "string",
                        "example": "0-100"
                    },
                    "confidence": {
                        "type": "number",
                        "format": "float",
                        "nullable": true,
                        "minimum": 0,
                        "maximum": 1
                    },
                    "confidence_meaning": {
                        "type": "string",
                        "example": "evidence sufficiency, not success probability"
                    },
                    "statement": {
                        "type": "string"
                    },
                    "reasoning_summary": {
                        "type": "string",
                        "description": "Concise evidence basis, not hidden chain-of-thought."
                    },
                    "flags": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "method_version": {
                        "type": "string"
                    },
                    "generated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "valid_until": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                }
            },
            "DerivedMetric": {
                "type": "object",
                "required": [
                    "metric_id",
                    "name",
                    "value",
                    "unit",
                    "window_start",
                    "window_end",
                    "formula_version",
                    "method_summary",
                    "metric_confidence",
                    "calculated_at",
                    "evidence_role"
                ],
                "properties": {
                    "metric_id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "value": {
                        "nullable": true,
                        "oneOf": [
                            {
                                "type": "number"
                            },
                            {
                                "type": "string"
                            }
                        ]
                    },
                    "unit": {
                        "type": "string",
                        "nullable": true
                    },
                    "window_start": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "window_end": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "formula_version": {
                        "type": "string"
                    },
                    "method_summary": {
                        "type": "string",
                        "nullable": true
                    },
                    "metric_confidence": {
                        "type": "number",
                        "format": "float",
                        "nullable": true
                    },
                    "calculated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "evidence_role": {
                        "type": "string",
                        "nullable": true
                    }
                }
            },
            "ObservationSource": {
                "type": "object",
                "required": [
                    "key",
                    "name",
                    "type",
                    "base_url",
                    "evidence_url"
                ],
                "properties": {
                    "key": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "type": {
                        "type": "string"
                    },
                    "base_url": {
                        "type": "string",
                        "format": "uri",
                        "nullable": true
                    },
                    "evidence_url": {
                        "type": "string",
                        "format": "uri",
                        "nullable": true
                    }
                }
            },
            "Observation": {
                "type": "object",
                "required": [
                    "observation_id",
                    "fact_type",
                    "value",
                    "unit",
                    "metric_scope",
                    "window_days",
                    "observed_at",
                    "captured_at",
                    "source",
                    "raw_hash"
                ],
                "properties": {
                    "observation_id": {
                        "type": "integer"
                    },
                    "fact_type": {
                        "type": "string"
                    },
                    "value": {
                        "nullable": true,
                        "oneOf": [
                            {
                                "type": "number"
                            },
                            {
                                "type": "string"
                            }
                        ]
                    },
                    "unit": {
                        "type": "string",
                        "nullable": true
                    },
                    "metric_scope": {
                        "type": "string",
                        "nullable": true
                    },
                    "window_days": {
                        "type": "integer",
                        "nullable": true
                    },
                    "observed_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "captured_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "source": {
                        "$ref": "#/components/schemas/ObservationSource"
                    },
                    "raw_hash": {
                        "type": "string",
                        "nullable": true
                    }
                }
            },
            "Provenance": {
                "type": "object",
                "required": [
                    "observation_count",
                    "observations",
                    "note"
                ],
                "properties": {
                    "observation_count": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "observations": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Observation"
                        }
                    },
                    "note": {
                        "type": "string"
                    }
                }
            },
            "MarketCheckResponse": {
                "type": "object",
                "required": [
                    "success",
                    "product",
                    "api_version",
                    "price_usd",
                    "paid",
                    "payment_reference",
                    "request",
                    "assessment",
                    "derived_metrics",
                    "provenance",
                    "limitations",
                    "checked_at"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "example": true
                    },
                    "product": {
                        "type": "string",
                        "example": "Ai for 500 Market Check"
                    },
                    "api_version": {
                        "type": "string",
                        "example": "4.1.3"
                    },
                    "price_usd": {
                        "type": "string",
                        "example": "0.05"
                    },
                    "paid": {
                        "type": "boolean",
                        "example": true
                    },
                    "payment_reference": {
                        "type": "string",
                        "nullable": true
                    },
                    "request": {
                        "$ref": "#/components/schemas/MarketCheckResolvedRequest"
                    },
                    "assessment": {
                        "$ref": "#/components/schemas/Assessment"
                    },
                    "derived_metrics": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/DerivedMetric"
                        }
                    },
                    "provenance": {
                        "$ref": "#/components/schemas/Provenance"
                    },
                    "limitations": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "checked_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "ApiError": {
                "type": "object",
                "required": [
                    "success",
                    "error",
                    "message"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "example": false
                    },
                    "error": {
                        "type": "string",
                        "example": "payment_required"
                    },
                    "message": {
                        "type": "string"
                    },
                    "product": {
                        "type": "string",
                        "nullable": true
                    },
                    "price_usd": {
                        "type": "string",
                        "nullable": true
                    },
                    "payment": {
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": true
                    }
                }
            }
        }
    }
}