{
  "openapi": "3.1.0",
  "info": {
    "title": "Beneat public research API",
    "version": "2026-09-08",
    "description": "Free, unauthenticated JSON endpoints behind Beneat's public tools: the Hyperliquid wallet scan (Trader Quality Score for any public Hyperliquid wallet, from its perp fills), Beneat Market Pulse (crypto momentum screener for Binance memecoin perpetuals, refreshed every 60 seconds) and Beneat Supply Watch (token supply and unlock screener for 25 assets, refreshed daily from primary sources). Research only, not investment advice.",
    "contact": {
      "name": "Beneat",
      "url": "https://beneat.ai",
      "email": "info@beneat.ai"
    },
    "termsOfService": "https://beneat.ai/terms"
  },
  "servers": [
    {
      "url": "https://beneat.ai"
    }
  ],
  "externalDocs": {
    "description": "LLM reference",
    "url": "https://beneat.ai/llms-full.txt"
  },
  "paths": {
    "/api/trader-card": {
      "get": {
        "operationId": "getTraderQualityScore",
        "summary": "Score a Hyperliquid wallet (Trader Quality Score)",
        "description": "Scores any public Hyperliquid wallet's perp trading over a lookback window from its public fills. Returns the Trader Quality Score (0-100) and tier, six behavioral dimensions, the costliest detected pattern, realized P&L, worst drawdown and closed-trade count. No signup or signature. Needs at least 5 closed perp trades; otherwise insufficientData is true. Rate limited per client IP to a small number of distinct addresses per minute. Human view: https://beneat.ai/brain/{address}.",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "description": "Hyperliquid (EVM) wallet address, 0x-prefixed 40 hex characters",
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          },
          {
            "name": "days",
            "in": "query",
            "description": "Lookback window in days",
            "schema": {
              "type": "integer",
              "minimum": 7,
              "maximum": 90,
              "default": 30
            }
          },
          {
            "name": "style",
            "in": "query",
            "description": "Optional cold-start prior; the detected style from fills takes precedence",
            "schema": {
              "type": "string",
              "enum": [
                "scalper",
                "day_trader",
                "swing",
                "position"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trader Quality Score payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TraderQualityScoreResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid address"
          },
          "429": {
            "description": "Rate limited; retry after the Retry-After header"
          },
          "502": {
            "description": "Analysis service unavailable"
          }
        }
      }
    },
    "/api/screener": {
      "get": {
        "operationId": "getMarketPulse",
        "summary": "Beneat Market Pulse ranking",
        "description": "Ranked memecoin perpetual markets with opportunity score, setup state, alpha, activity, execution, crowding, price, taker flow, open interest, funding and a page URL. Cached 60 seconds.",
        "parameters": [
          {
            "name": "symbol",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Ticker (BONK) or full Binance symbol (1000BONKUSDT). Returns a single `row`."
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "prime",
                "constructive",
                "mixed",
                "avoid"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranking or single market",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketPulseResponse"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Unknown market"
          },
          "502": {
            "description": "Binance market data unavailable"
          }
        }
      }
    },
    "/api/screener/deflationary": {
      "get": {
        "operationId": "getSupplyWatch",
        "summary": "Beneat Supply Watch ranking",
        "description": "25 tokens with supply verdict, 12-month net supply estimate and method, unlock percentage, schedule status, mechanism, scores, sources and reconciliation. Includes the normalized release calendar. Cached one hour.",
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Returns a single `row` plus that token's calendar."
          },
          {
            "name": "verdict",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "shrinking",
                "near-flat",
                "inflationary",
                "unverified"
              ]
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranking or single token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SupplyWatchResponse"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Token not covered"
          }
        }
      }
    },
    "/api/screener/deflationary/calendar": {
      "get": {
        "operationId": "getUnlockCalendar",
        "summary": "Dated token release calendar",
        "description": "Cliff, step and linear releases normalized into dated events with amount and share of reference supply. Opaque and governance-dependent releases are excluded rather than estimated.",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "description": "Upcoming UTC window from today, exclusive end. Not valid with historical scope.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365
            }
          },
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scope",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "upcoming",
                "historical"
              ],
              "default": "upcoming"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 250
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calendar events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalendarResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/screener/deflationary/calendar/ics": {
      "get": {
        "operationId": "getUnlockCalendarIcs",
        "summary": "Release calendar as iCalendar (subscribe from any calendar app)",
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "past",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 400,
              "default": 30
            },
            "description": "Include releases from the last N days"
          }
        ],
        "responses": {
          "200": {
            "description": "text/calendar",
            "content": {
              "text/calendar": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/screener/deflationary/calendar/rss": {
      "get": {
        "operationId": "getUnlockCalendarRss",
        "summary": "Upcoming releases as an RSS 2.0 feed",
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365,
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "application/rss+xml",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/screener/deflationary/history": {
      "get": {
        "operationId": "getSupplyHistory",
        "summary": "Daily market, chain-supply and reconciliation snapshots",
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 400,
              "default": 90
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshots, oldest first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MarketPulseRow": {
        "type": "object",
        "properties": {
          "symbol": {
            "type": "string",
            "example": "1000BONKUSDT"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "chain": {
            "type": "string"
          },
          "opportunityRank": {
            "type": [
              "integer",
              "null"
            ]
          },
          "opportunityScore": {
            "type": [
              "integer",
              "null"
            ],
            "description": "0-100 blended research score"
          },
          "opportunityState": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "prime",
              "constructive",
              "mixed",
              "avoid",
              null
            ]
          },
          "alphaScore": {
            "type": [
              "integer",
              "null"
            ]
          },
          "volatilityIndex": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Activity score"
          },
          "tradeabilityScore": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Execution quality"
          },
          "crowdingScore": {
            "type": [
              "integer",
              "null"
            ]
          },
          "modelDataQuality": {
            "type": "integer"
          },
          "price": {
            "type": [
              "number",
              "null"
            ]
          },
          "change24h": {
            "type": [
              "number",
              "null"
            ]
          },
          "quoteVolume24h": {
            "type": [
              "number",
              "null"
            ]
          },
          "takerBuySellRatio": {
            "type": [
              "number",
              "null"
            ]
          },
          "openInterestChange1h": {
            "type": [
              "number",
              "null"
            ]
          },
          "openInterestChange4h": {
            "type": [
              "number",
              "null"
            ]
          },
          "fundingRatePercent": {
            "type": [
              "number",
              "null"
            ]
          },
          "premiumBps": {
            "type": [
              "number",
              "null"
            ]
          },
          "spreadBps": {
            "type": [
              "number",
              "null"
            ]
          },
          "setupFlags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sparkline": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Hourly closes, oldest first"
          },
          "page": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "MarketPulseResponse": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "live",
              "partial",
              "unavailable"
            ]
          },
          "asOf": {
            "type": "string",
            "format": "date-time"
          },
          "refreshSeconds": {
            "type": "integer"
          },
          "source": {
            "type": "string"
          },
          "warning": {
            "type": [
              "string",
              "null"
            ]
          },
          "summary": {
            "type": "object"
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MarketPulseRow"
            }
          },
          "row": {
            "$ref": "#/components/schemas/MarketPulseRow"
          }
        }
      },
      "SupplyWatchRow": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer"
          },
          "ticker": {
            "type": "string",
            "example": "HYPE"
          },
          "project": {
            "type": "string"
          },
          "verdict": {
            "type": "string",
            "enum": [
              "shrinking",
              "near-flat",
              "inflationary",
              "unverified"
            ]
          },
          "scores": {
            "type": "object",
            "properties": {
              "structural": {
                "type": "integer"
              },
              "supply": {
                "type": "integer"
              },
              "float": {
                "type": "integer"
              },
              "durability": {
                "type": "integer"
              },
              "execution": {
                "type": "integer"
              }
            }
          },
          "netSupply12mPct": {
            "type": [
              "number",
              "null"
            ]
          },
          "netSupplyLabel": {
            "type": "string"
          },
          "supplyEstimate": {
            "type": "object",
            "description": "status (measured, provisional, policy, target, insufficient-history), method, observationCount, windowDays, low/high range"
          },
          "unlock12mPct": {
            "type": [
              "number",
              "null"
            ],
            "description": "Known releases over 12 months as % of circulating supply; null when the schedule is not disclosed"
          },
          "unlockBand": {
            "type": "string",
            "enum": [
              "none",
              "low",
              "moderate",
              "high",
              "extreme",
              "unknown"
            ]
          },
          "scheduleStatus": {
            "type": "string",
            "enum": [
              "modeled",
              "partial",
              "dynamic",
              "complete",
              "opaque"
            ]
          },
          "circulatingSupply": {
            "type": "number"
          },
          "referenceSupply": {
            "type": [
              "number",
              "null"
            ]
          },
          "marketCapM": {
            "type": "number",
            "description": "USD millions"
          },
          "mechanismLabel": {
            "type": "string"
          },
          "destination": {
            "type": "string",
            "enum": [
              "burn",
              "lock",
              "treasury",
              "redistribute",
              "mixed",
              "none"
            ]
          },
          "dataTier": {
            "type": "integer",
            "enum": [
              1,
              2,
              3
            ]
          },
          "evidence": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "calendarEvents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CalendarEvent"
            }
          },
          "reconciliation": {
            "type": "object"
          },
          "page": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "SupplyWatchResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "asOf": {
            "type": "string",
            "format": "date-time"
          },
          "calculatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "warning": {
            "type": "string"
          },
          "summary": {
            "type": "object"
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SupplyWatchRow"
            }
          },
          "row": {
            "$ref": "#/components/schemas/SupplyWatchRow"
          },
          "calendar": {
            "type": "object",
            "properties": {
              "upcoming": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CalendarEvent"
                }
              },
              "historical": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CalendarEvent"
                }
              }
            }
          }
        }
      },
      "CalendarEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "ticker": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date-time"
          },
          "category": {
            "type": "string"
          },
          "amount": {
            "type": "number"
          },
          "pctOfReferenceSupply": {
            "type": [
              "number",
              "null"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "cliff",
              "linear",
              "step"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "historical",
              "upcoming"
            ]
          },
          "estimatedDate": {
            "type": "boolean"
          }
        }
      },
      "CalendarResponse": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "type": "integer"
          },
          "asOf": {
            "type": "string",
            "format": "date-time"
          },
          "scope": {
            "type": "string"
          },
          "ticker": {
            "type": [
              "string",
              "null"
            ]
          },
          "count": {
            "type": "integer"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CalendarEvent"
            }
          }
        }
      },
      "TraderQualityScoreResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "address": {
            "type": "string"
          },
          "detectedStyle": {
            "type": "string",
            "enum": [
              "scalper",
              "day_trader",
              "swing",
              "position"
            ]
          },
          "periodDays": {
            "type": "integer"
          },
          "coverage": {
            "type": "object",
            "properties": {
              "actualDays": {
                "type": "number"
              },
              "truncated": {
                "type": "boolean"
              },
              "fromMs": {
                "type": "integer"
              },
              "toMs": {
                "type": "integer"
              }
            }
          },
          "tradeCount": {
            "type": "integer",
            "description": "Closed perp trades in the window"
          },
          "insufficientData": {
            "type": "boolean",
            "description": "True when fewer than 5 closed trades were found"
          },
          "tqs": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Trader Quality Score"
          },
          "tier": {
            "type": "string",
            "enum": [
              "bronze",
              "silver",
              "gold",
              "diamond"
            ]
          },
          "stats": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "enum": [
                    "EMO",
                    "DIS",
                    "PAT",
                    "RSK",
                    "WR",
                    "RR"
                  ]
                },
                "label": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "value": {
                  "type": "number"
                },
                "display": {
                  "type": "string"
                }
              }
            }
          },
          "strengths": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StatHighlight"
            }
          },
          "focus": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StatHighlight"
            }
          },
          "netPnl": {
            "type": "number",
            "description": "Realized P&L in quote currency (USDC)"
          },
          "maxDrawdownQuote": {
            "type": "number",
            "description": "Worst drawdown in quote currency"
          },
          "headlinePattern": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "revenge_trading",
                  "fomo",
                  "overconfidence",
                  "panic",
                  "overtrading",
                  "tilt",
                  "patience"
                ]
              },
              "label": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "severity": {
                "type": "string",
                "enum": [
                  "low",
                  "medium",
                  "high"
                ]
              },
              "occurrences": {
                "type": "integer"
              },
              "sharePct": {
                "type": "number"
              }
            }
          },
          "error": {
            "type": "string"
          }
        }
      },
      "StatHighlight": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "display": {
            "type": "string"
          },
          "value": {
            "type": "number"
          },
          "sentence": {
            "type": "string"
          }
        }
      }
    }
  }
}