{"openapi":"3.1.0","info":{"title":"Hyperstition Developer API","version":"1.2.0","description":"Stable read-only access to indexed Hyperstition launches, markets, creators, pair tokens and protocol activity."},"servers":[{"url":"/v1"}],"tags":[{"name":"Service"},{"name":"Launches"},{"name":"Creators"},{"name":"Protocol"}],"paths":{"/health":{"get":{"tags":["Service"],"operationId":"getHealth","summary":"Check API and indexer readiness","responses":{"200":{"description":"Service status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthEnvelope"}}}},"503":{"description":"Indexer unavailable"}}}},"/openapi.json":{"get":{"tags":["Service"],"operationId":"getOpenApi","summary":"Download this OpenAPI document","responses":{"200":{"description":"OpenAPI 3.1 document"}}}},"/launches":{"get":{"tags":["Launches"],"operationId":"listLaunches","summary":"Discover launches","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string","maxLength":100}},{"name":"phase","in":"query","schema":{"type":"string","enum":["all","curve","pool"],"default":"all"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","oldest","recent","marketCap","volume","live"],"default":"newest"},"description":"live lists only launches with an outside-wallet trade in the last 24 hours, ranked by distinct outside wallets in the last hour, then the last 24 hours, then the latest outside trade, then token address. Outside means not the creator, the current creator fee recipient, the reward-lock beneficiary or a wallet ever credited this launch's creator rewards; trades in the launch block and the next three never count. Every other sort lists all launches."},{"name":"pairToken","in":"query","schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}],"responses":{"200":{"description":"A bounded page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchPageEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/launches/{token}":{"get":{"tags":["Launches"],"operationId":"getLaunch","summary":"Get one launch","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}],"responses":{"200":{"description":"Launch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/launches/{token}/trades":{"get":{"tags":["Launches"],"operationId":"listTrades","summary":"List launch trades","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"kind","in":"query","schema":{"type":"string","enum":["curveBuy","curveSell","poolBuy","poolSell"]}}],"responses":{"200":{"description":"A bounded page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradePageEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/launches/{token}/candles":{"get":{"tags":["Launches"],"operationId":"listCandles","summary":"List launch candles newest first","description":"One-second requests require a source and return at most 300 seconds of recent market activity.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"interval","in":"query","required":true,"schema":{"type":"integer","enum":[1,60,300,3600,86400]}},{"name":"source","in":"query","schema":{"type":"string","enum":["curve","pool"]},"description":"Required when interval=1."}],"responses":{"200":{"description":"A bounded page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandlePageEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/launches/{token}/holders":{"get":{"tags":["Launches"],"operationId":"listHolders","summary":"List positive holder balances","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"A bounded page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolderPageEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/creators/{address}":{"get":{"tags":["Creators"],"operationId":"getCreatorProfile","summary":"Get a creator profile and bounded activity","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Creator profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/pairs":{"get":{"tags":["Protocol"],"operationId":"listPairs","summary":"List indexed pair tokens","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"approved","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"A bounded page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PairPageEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/protocol/stats":{"get":{"tags":["Protocol"],"operationId":"getProtocolStats","summary":"Get aggregate protocol activity","responses":{"200":{"description":"Protocol statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtocolStatsEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/leaderboards/{category}":{"get":{"tags":["Protocol"],"operationId":"getLeaderboard","summary":"Get a points leaderboard (creators, tokens or traders)","parameters":[{"name":"category","in":"path","required":true,"schema":{"type":"string","enum":["creators","tokens","traders"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"window","in":"query","schema":{"type":"string","enum":["weekly","allTime"],"default":"allTime"}}],"responses":{"200":{"description":"A bounded page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaderboardPageEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"responses":{"BadRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected read failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"UintString":{"type":"string","pattern":"^\\d+$"},"Pagination":{"type":"object","required":["limit","hasNext","nextCursor"],"properties":{"limit":{"type":"integer"},"hasNext":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"asOf":{"type":"integer","description":"sort=live only: unix seconds the activity windows end at. The cursor keeps it, so every page ranks the same windows."}}},"Launch":{"type":"object","required":["token","curve","name","symbol","deployer","creatorFeeRecipient","pairToken","quoteDecimals","supply","graduationThreshold","feeBps","creatorTaxBps","protocolFeeShareBps","rewardLockUntil","stakingAllocation","phase","quoteReserve","priceQuote","marketCapQuote","volumeQuote","txCount","holderCount","feesQuote","createdAt","createdBlock"],"properties":{"token":{"$ref":"#/components/schemas/Address"},"curve":{"$ref":"#/components/schemas/Address"},"name":{"type":"string"},"symbol":{"type":"string"},"logo":{"type":["string","null"]},"description":{"type":["string","null"]},"twitter":{"type":["string","null"]},"telegram":{"type":["string","null"]},"website":{"type":["string","null"]},"farcaster":{"type":["string","null"]},"deployer":{"$ref":"#/components/schemas/Address"},"creatorFeeRecipient":{"$ref":"#/components/schemas/Address"},"pairToken":{"$ref":"#/components/schemas/Address"},"quoteDecimals":{"type":"integer"},"supply":{"$ref":"#/components/schemas/UintString"},"graduationThreshold":{"$ref":"#/components/schemas/UintString"},"feeBps":{"type":"integer"},"creatorTaxBps":{"type":"integer"},"protocolFeeShareBps":{"type":"integer"},"rewardLockUntil":{"type":"integer"},"stakingAllocation":{"$ref":"#/components/schemas/UintString"},"phase":{"type":"string","enum":["curve","swept","pool","rescued"]},"poolId":{"type":["string","null"]},"quoteReserve":{"$ref":"#/components/schemas/UintString"},"priceQuote":{"type":"number"},"marketCapQuote":{"type":"number"},"volumeQuote":{"$ref":"#/components/schemas/UintString"},"txCount":{"type":"integer"},"holderCount":{"type":"integer"},"feesQuote":{"$ref":"#/components/schemas/UintString"},"createdAt":{"type":"integer"},"createdBlock":{"$ref":"#/components/schemas/UintString"},"graduatedAt":{"type":["integer","null"]},"lastTradeAt":{"type":["integer","null"]},"outsideWallets1h":{"type":"integer","description":"sort=live only: distinct outside wallets that traded in the last hour."},"outsideWallets24h":{"type":"integer","description":"sort=live only: distinct outside wallets that traded in the last 24 hours."},"lastOutsideTradeAt":{"type":"integer","description":"sort=live only: unix seconds of the latest outside-wallet trade."}}},"Trade":{"type":"object","required":["id","token","kind","trader","quoteAmount","tokenAmount","fee","priceQuote","txHash","block","timestamp"],"properties":{"id":{"type":"string"},"token":{"$ref":"#/components/schemas/Address"},"kind":{"type":"string","enum":["curveBuy","curveSell","poolBuy","poolSell"]},"trader":{"$ref":"#/components/schemas/Address"},"quoteAmount":{"$ref":"#/components/schemas/UintString"},"tokenAmount":{"$ref":"#/components/schemas/UintString"},"fee":{"$ref":"#/components/schemas/UintString"},"priceQuote":{"type":"number"},"txHash":{"type":"string"},"block":{"$ref":"#/components/schemas/UintString"},"timestamp":{"type":"integer"}}},"Candle":{"type":"object","required":["token","source","interval","bucket","open","high","low","close","volumeQuote","trades"],"properties":{"token":{"$ref":"#/components/schemas/Address"},"source":{"type":"string","enum":["curve","pool"]},"interval":{"type":"integer","enum":[1,60,300,3600,86400]},"bucket":{"type":"integer"},"open":{"type":"number"},"high":{"type":"number"},"low":{"type":"number"},"close":{"type":"number"},"volumeQuote":{"$ref":"#/components/schemas/UintString"},"trades":{"type":"integer"}}},"Holder":{"type":"object","required":["account","balance"],"properties":{"account":{"$ref":"#/components/schemas/Address"},"balance":{"$ref":"#/components/schemas/UintString"}}},"Pair":{"type":"object","required":["address","symbol","decimals","approved"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"symbol":{"type":"string"},"decimals":{"type":"integer"},"approved":{"type":"boolean"}}},"ProtocolStats":{"type":"object","required":["id","launches","graduated","trades","uniqueCreators","hyperstitionBurned","hyperstitionTreasuryRetained","creatorHyperstitionCredited","protocolHyperstitionConverted","feeEvents","totalStaked","updatedAt"],"properties":{"id":{"type":"integer"},"launches":{"type":"integer"},"graduated":{"type":"integer"},"trades":{"type":"integer"},"uniqueCreators":{"type":"integer"},"hyperstitionBurned":{"$ref":"#/components/schemas/UintString"},"hyperstitionTreasuryRetained":{"$ref":"#/components/schemas/UintString"},"creatorHyperstitionCredited":{"$ref":"#/components/schemas/UintString"},"protocolHyperstitionConverted":{"$ref":"#/components/schemas/UintString"},"feeEvents":{"type":"integer"},"totalStaked":{"$ref":"#/components/schemas/UintString"},"updatedAt":{"type":"integer"}}},"LaunchEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Launch"}}},"LaunchPageEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Launch"}}}},"meta":{"$ref":"#/components/schemas/Pagination"}}},"TradePageEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Trade"}}}},"meta":{"$ref":"#/components/schemas/Pagination"}}},"CandlePageEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Candle"}}}},"meta":{"$ref":"#/components/schemas/Pagination"}}},"HolderPageEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Holder"}}}},"meta":{"$ref":"#/components/schemas/Pagination"}}},"PairPageEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Pair"}}}},"meta":{"$ref":"#/components/schemas/Pagination"}}},"ProtocolStatsEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ProtocolStats"}}},"LeaderboardEntry":{"type":"object","required":["score","basePoints","multiplier"],"properties":{"score":{"type":"number"},"basePoints":{"type":"number"},"multiplier":{"type":"number"},"address":{"$ref":"#/components/schemas/Address"},"launches":{"type":"integer"},"graduations":{"type":"integer"},"holdersGained":{"type":"integer"},"earnedFees":{"$ref":"#/components/schemas/UintString"},"realizedVolume":{"$ref":"#/components/schemas/UintString"},"freshVolume":{"type":"number"},"staleVolume":{"type":"number"},"graduationBuys":{"type":"integer"},"token":{"$ref":"#/components/schemas/Address"},"name":{"type":"string"},"symbol":{"type":"string"},"fees":{"$ref":"#/components/schemas/UintString"},"uniqueBuyers":{"type":"integer"},"holderCount":{"type":"integer"}}},"LeaderboardPageEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LeaderboardEntry"}}}},"meta":{"$ref":"#/components/schemas/Pagination"}}},"HealthEnvelope":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["status","version","indexedAt"],"properties":{"status":{"type":"string","enum":["ready","syncing"]},"version":{"type":"string"},"indexedAt":{"type":["integer","null"]}}}}},"CreatorEnvelope":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["address","created","receiving","holdings","rewardLocks"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"account":{"type":["object","null"],"additionalProperties":true},"created":{"type":"array","items":{"$ref":"#/components/schemas/Launch"}},"receiving":{"type":"array","items":{"$ref":"#/components/schemas/Launch"}},"holdings":{"type":"array","items":{"type":"object","additionalProperties":true}},"rewardLocks":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}}