{
  "openapi": "3.0.3",
  "info": {
    "title": "MemeScore API",
    "version": "1.0.0",
    "description": "Public HTTP API for a 0\u2013100 Solana memecoin risk score. There is no /v1/score route; use GET /v1/check. Analytics only; not financial advice. Never send a wallet, key, or recovery phrase.",
    "contact": {
      "name": "MemeScore",
      "url": "https://memescore.io/"
    }
  },
  "servers": [
    {
      "url": "https://memescore.io",
      "description": "This deployment (ASSAY_PUBLIC_URL)"
    }
  ],
  "tags": [
    {
      "name": "Score",
      "description": "Token risk checks"
    },
    {
      "name": "Discovery",
      "description": "Search, traders, feed"
    },
    {
      "name": "Account",
      "description": "Usage and public accuracy"
    }
  ],
  "paths": {
    "/v1/check": {
      "get": {
        "tags": [
          "Score"
        ],
        "summary": "Score a Solana token mint",
        "operationId": "checkMint",
        "security": [
          {
            "ApiKey": [],
            "Bearer": []
          }
        ],
        "parameters": [
          {
            "name": "mint",
            "in": "query",
            "required": true,
            "description": "Solana token mint address (base58, 32\u201344 characters).",
            "schema": {
              "type": "string",
              "minLength": 32,
              "maxLength": 44
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Score payload (v0, plus memescore_v1 when the mint is in the forward ledger)."
          },
          "400": {
            "description": "Malformed mint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Plan rate limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Busy or daily capacity reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "summary": "Search tokens by name or ticker",
        "operationId": "searchTokens",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "2\u201340 characters. Unauthenticated; not counted against check quotas; IP-throttled.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 40
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching Solana tokens, highest liquidity first."
          },
          "400": {
            "description": "Query length out of range",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many searches",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Search unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/traders": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "summary": "Tracked wallets that traded this mint",
        "operationId": "listTraders",
        "parameters": [
          {
            "name": "mint",
            "in": "query",
            "required": true,
            "description": "Solana token mint address (base58, 32\u201344 characters).",
            "schema": {
              "type": "string",
              "minLength": 32,
              "maxLength": 44
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked trader rows; anonymous callers see the free-plan cap."
          },
          "400": {
            "description": "Malformed mint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Traders unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/feed": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "summary": "Live graduation feed",
        "operationId": "graduationFeed",
        "security": [
          {
            "ApiKey": [],
            "Bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Feed payload"
          },
          "401": {
            "description": "Log in or send an API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Plan does not include the feed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Plan rate limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Feed unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Remaining daily and per-minute checks",
        "operationId": "getUsage",
        "security": [
          {
            "ApiKey": [],
            "Bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Quota remaining and plan name"
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/ledger": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Public forward ledger of timestamped scores",
        "operationId": "getLedger",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 300,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ledger rows"
          }
        }
      }
    },
    "/proof.json": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Public accuracy payload",
        "operationId": "getProof",
        "responses": {
          "200": {
            "description": "Accuracy record. Treat figures as a back-test until the forward test is posted."
          }
        }
      }
    },
    "/free/check": {
      "get": {
        "tags": [
          "Score"
        ],
        "summary": "Anonymous homepage check (IP daily cap)",
        "operationId": "freeCheck",
        "parameters": [
          {
            "name": "mint",
            "in": "query",
            "required": true,
            "description": "Solana token mint address (base58, 32\u201344 characters).",
            "schema": {
              "type": "string",
              "minLength": 32,
              "maxLength": 44
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Same score shape as /v1/check"
          },
          "400": {
            "description": "Malformed mint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Free daily or global cap",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Busy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Liveness",
        "operationId": "healthz",
        "responses": {
          "200": {
            "description": "{\"ok\": true}"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "Bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "ak_test_ or ak_live_"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "plan": {
            "type": "string"
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Human-readable API docs",
    "url": "https://memescore.io/docs"
  }
}