{
  "openapi": "3.1.0",
  "info": {
    "title": "BentCrypto Intelligence API",
    "version": "1.0.0",
    "description": "Crypto intelligence for humans and AI agents. The Token Risk endpoint is live in limited beta and is paid per request with x402 v2 (exact scheme) in USDC on Solana mainnet. All other BentCrypto products are not live and are therefore not described here.",
    "contact": { "name": "BentCrypto", "url": "https://bentcrypto.com/contact" },
    "x-payment": {
      "protocol": "x402",
      "x402Version": 2,
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "assetSymbol": "USDC",
      "assetDecimals": 6,
      "amount": "10000",
      "amountUsd": "0.01",
      "payTo": "5bZdrGYAbHdbVCqw7RVUpxma22kJehaQCHhp4nHuHCyy",
      "challengeHeader": "payment-required",
      "settlementHeader": "payment-response"
    },
    "x-cors": {
      "enabled": true,
      "allowedOrigins": [
        "https://bentcrypto.com",
        "https://www.bentcrypto.com",
        "https://bentcrypto.lovable.app"
      ],
      "allowedMethods": ["GET", "OPTIONS"],
      "exposedHeaders": ["payment-required", "payment-response", "x-request-id"]
    }
  },
  "servers": [
    {
      "url": "https://bentcrypto-x402-production.up.railway.app",
      "description": "Verified production deployment (limited beta)"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Service health",
        "description": "Unpaid health probe.",
        "responses": {
          "200": {
            "description": "Service is reachable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "service": { "type": "string", "example": "bentcrypto-x402" },
                    "release_stage": { "type": "string", "example": "beta" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/token/risk": {
      "get": {
        "operationId": "getTokenRisk",
        "summary": "Token Risk API",
        "description": "Returns a structured Solana token risk assessment. Requires an x402 v2 payment of exactly 10000 USDC base units ($0.01) per request. Payment is enforced before route validation: an unpaid request returns HTTP 402 with an empty JSON body and the base64-encoded payment requirements in the `payment-required` response header. Parameter validation errors (400) are only returned after a valid payment.",
        "parameters": [
          {
            "name": "chain",
            "in": "query",
            "required": true,
            "description": "Target chain. Only `solana` is supported.",
            "schema": { "type": "string", "enum": ["solana"] }
          },
          {
            "name": "address",
            "in": "query",
            "required": true,
            "description": "Solana mint address to analyze.",
            "schema": { "type": "string" },
            "example": "So11111111111111111111111111111111111111112"
          }
        ],
        "responses": {
          "200": {
            "description": "Risk report produced.",
            "headers": {
              "payment-response": {
                "description": "Base64-encoded settlement metadata, when present.",
                "schema": { "type": "string" }
              },
              "x-request-id": {
                "description": "Request correlation id.",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/TokenRiskReport" } }
            }
          },
          "400": {
            "description": "UNSUPPORTED_CHAIN, MISSING_ADDRESS or INVALID_ADDRESS. Route validation runs after a valid payment.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "402": {
            "description": "Payment required, returned before route validation. The body is an empty JSON object; the x402 v2 challenge is base64-encoded in the `payment-required` header.",
            "headers": {
              "payment-required": {
                "description": "Base64-encoded JSON payment requirements (see PaymentRequirements schema for the decoded shape).",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Empty object. The challenge is carried in the payment-required header, not in the body.",
                  "additionalProperties": false
                },
                "example": {}
              }
            }
          },
          "500": {
            "description": "INTERNAL_GATEWAY_ERROR.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "502": {
            "description": "RISK_ENGINE_UNAVAILABLE.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "503": {
            "description": "GATEWAY_NOT_CONFIGURED.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "504": {
            "description": "RISK_ENGINE_TIMEOUT.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RiskLevel": {
        "type": "string",
        "enum": ["low", "moderate", "high", "critical", "insufficient_data"]
      },
      "CategoryScore": {
        "type": "object",
        "properties": {
          "score": { "type": "number" },
          "available_max": { "type": "number" },
          "configured_max": { "type": "number" }
        }
      },
      "Signal": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "category": { "type": "string" },
          "status": { "type": "string" },
          "value": {},
          "points": { "type": "number" },
          "max_points": { "type": "number" },
          "severity": { "type": "string" },
          "context": { "type": ["object", "null"], "additionalProperties": true }
        }
      },
      "Warning": {
        "type": "object",
        "properties": {
          "code": { "type": "string" },
          "severity": { "type": "string" },
          "message": { "type": "string" }
        }
      },
      "TokenRiskReport": {
        "type": "object",
        "required": ["success", "risk", "confidence"],
        "properties": {
          "success": { "type": "boolean" },
          "chain": { "type": "string" },
          "address": { "type": "string" },
          "asset_context": {
            "type": "object",
            "properties": {
              "type": { "type": "string" },
              "registry_match": {}
            }
          },
          "token": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "symbol": { "type": "string" }
            }
          },
          "risk": {
            "type": "object",
            "properties": {
              "score": { "type": "number" },
              "level": { "$ref": "#/components/schemas/RiskLevel" },
              "provisional": { "type": "boolean" },
              "base_score": { "type": "number" },
              "floor_applied": {},
              "override_applied": {}
            }
          },
          "confidence": {
            "type": "object",
            "properties": {
              "score": { "type": "number" },
              "level": { "type": "string" },
              "coverage_percent": { "type": "number" },
              "source_agreement_percent": { "type": "number" },
              "freshness_percent": { "type": "number" }
            }
          },
          "categories": {
            "type": "object",
            "properties": {
              "authority_control": { "$ref": "#/components/schemas/CategoryScore" },
              "holder_concentration": { "$ref": "#/components/schemas/CategoryScore" },
              "liquidity_tradability": { "$ref": "#/components/schemas/CategoryScore" },
              "launch_manipulation": { "$ref": "#/components/schemas/CategoryScore" },
              "maturity_trust": { "$ref": "#/components/schemas/CategoryScore" }
            },
            "additionalProperties": { "$ref": "#/components/schemas/CategoryScore" }
          },
          "signals": {
            "type": "object",
            "description": "Object keyed by signal name.",
            "additionalProperties": { "$ref": "#/components/schemas/Signal" }
          },
          "holder_concentration": {
            "type": "object",
            "properties": {
              "raw_top10_percent": { "type": ["number", "null"] },
              "effective_top10_percent": { "type": ["number", "null"] },
              "single_holder_percent": { "type": ["number", "null"] },
              "excluded_percent": { "type": ["number", "null"] },
              "excluded_account_types": { "type": "array", "items": { "type": "string" } },
              "classification_complete": { "type": "boolean" }
            }
          },
          "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } },
          "summary": { "type": "string" },
          "metadata": {
            "type": "object",
            "properties": {
              "api_schema_version": { "type": "string" },
              "risk_engine_version": { "type": "string" },
              "asset_registry_version": { "type": "string" },
              "release_stage": { "type": "string" },
              "evaluated_at": { "type": "string" },
              "data_sources": { "type": "object", "additionalProperties": true },
              "provider_errors": {},
              "cache": { "type": "object", "additionalProperties": true }
            }
          }
        }
      },
      "PaymentRequirements": {
        "type": "object",
        "description": "Decoded contents of the base64-encoded `payment-required` response header. This is never returned as the 402 response body.",
        "properties": {
          "x402Version": { "type": "integer", "const": 2 },
          "error": { "type": "string" },
          "resource": {
            "type": "object",
            "properties": {
              "url": { "type": "string" },
              "description": { "type": "string" },
              "mimeType": { "type": "string" }
            }
          },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": { "type": "string", "const": "exact" },
                "network": { "type": "string", "const": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" },
                "amount": { "type": "string", "const": "10000" },
                "asset": { "type": "string", "const": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" },
                "payTo": { "type": "string", "const": "5bZdrGYAbHdbVCqw7RVUpxma22kJehaQCHhp4nHuHCyy" },
                "maxTimeoutSeconds": { "type": "integer" },
                "extra": { "type": "object", "additionalProperties": true }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["success", "error", "message"],
        "properties": {
          "success": { "type": "boolean", "const": false },
          "error": {
            "type": "string",
            "description": "Stable machine-readable error code.",
            "enum": [
              "GATEWAY_NOT_CONFIGURED",
              "UNSUPPORTED_CHAIN",
              "MISSING_ADDRESS",
              "INVALID_ADDRESS",
              "RISK_ENGINE_TIMEOUT",
              "RISK_ENGINE_UNAVAILABLE",
              "INTERNAL_GATEWAY_ERROR"
            ]
          },
          "message": { "type": "string" },
          "request_id": { "type": "string" }
        }
      }
    }
  }
}