{"openapi":"3.1.0","info":{"title":"Murmurn Public API","version":"1.0.0","summary":"Read-only market and trader data from Murmurn, the social crypto trading web app.","description":"Public, read-only JSON endpoints behind murmurn.com: trending and newly launched tokens, token detail with safety checks, price candles, top holders, the trader leaderboard, public trader profiles and Trust Scores, and site-wide stats. No API key or sign-in is needed. Every endpoint is a GET and answers JSON. Errors are JSON objects with `error` (a sentence), `code` (a stable value), an optional `hint`, and `docs`. Requests are rate limited per IP address; a refused request answers 429 with `Retry-After`, `RateLimit-Policy` and `RateLimit` headers (IETF draft-ietf-httpapi-ratelimit-headers). Trading, wallets and account settings are not part of this API.","contact":{"name":"Murmurn support","email":"support@murmurn.com","url":"https://murmurn.com/contact"},"termsOfService":"https://murmurn.com/terms"},"externalDocs":{"description":"Murmurn developer docs","url":"https://murmurn.com/docs"},"servers":[{"url":"https://murmurn.com","description":"Production"}],"tags":[{"name":"Tokens","description":"Token lists, detail, candles and holders."},{"name":"Traders","description":"The leaderboard and public trader profiles."},{"name":"Platform","description":"Site-wide stats, search and the live ticker."}],"paths":{"/api/stats/public":{"get":{"operationId":"getPublicStats","tags":["Platform"],"summary":"Platform totals","description":"Registered traders, confirmed trades and USDC volume in the last 24 hours, and the 8 most recent trades (anonymised). `available` is false before there is any trade to show. Cached for 5 minutes.","responses":{"200":{"description":"Platform totals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicStats"}}}}}}},"/api/search":{"get":{"operationId":"search","tags":["Platform"],"summary":"Search tokens and traders","description":"Finds tokens by symbol, name or address, and traders by handle. Queries shorter than 2 characters return empty lists. Rate limit: 40 requests per 60 seconds per IP address.","parameters":[{"name":"q","in":"query","required":true,"description":"Search text, 2 to 64 characters.","schema":{"type":"string","minLength":2,"maxLength":64},"example":"bonk"},{"name":"only","in":"query","required":false,"description":"Set to `traders` to skip the token search.","schema":{"type":"string","enum":["traders"]}}],"responses":{"200":{"description":"Matching tokens and traders.","content":{"application/json":{"schema":{"type":"object","required":["tokens","traders"],"properties":{"tokens":{"type":"array","items":{"$ref":"#/components/schemas/TokenRow"}},"traders":{"type":"array","items":{"$ref":"#/components/schemas/Person"}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/ticker":{"get":{"operationId":"getTicker","tags":["Platform"],"summary":"Live prices for the top trending Solana tokens","description":"Up to 12 tokens with their live USD price and 24 hour change, refreshed every few seconds. Rate limit: 90 requests per 60 seconds per IP address.","responses":{"200":{"description":"Ticker rows.","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["symbol","priceUsd"],"properties":{"symbol":{"type":"string"},"logo":{"anyOf":[{"type":"string"},{"type":"null"}]},"priceUsd":{"type":"number"},"change24hPct":{"anyOf":[{"type":"number"},{"type":"null"}]}}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/tokens/trending":{"get":{"operationId":"listTrendingTokens","tags":["Tokens"],"summary":"Token lists: trending, most held, blue chips, graduated","description":"One of four token lists. With no chain, every live chain is included and interleaved. Rate limit: 90 requests per 60 seconds per IP address.","parameters":[{"name":"tab","in":"query","required":false,"description":"`trending`: trending pools. `most-held`: tokens in the most open positions on Murmurn. `crypto`: established blue chips. `graduated`: launches that moved to a full DEX pool.","schema":{"type":"string","enum":["trending","most-held","crypto","graduated"],"default":"trending"}},{"name":"chain","in":"query","required":false,"description":"Limit the list to one chain.","schema":{"type":"string","enum":["solana","base"]}}],"responses":{"200":{"description":"The token list.","content":{"application/json":{"schema":{"type":"object","required":["tokens"],"properties":{"tokens":{"type":"array","items":{"$ref":"#/components/schemas/TokenRow"}}}}}}},"400":{"description":"The query parameters are not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/tokens/most-held":{"get":{"operationId":"listMostHeldTokens","tags":["Tokens"],"summary":"Tokens most held by Murmurn traders","description":"Tokens in the most open positions on Murmurn. Rate limit: 90 requests per 60 seconds per IP address.","parameters":[{"name":"chain","in":"query","required":false,"description":"Limit the list to one chain.","schema":{"type":"string","enum":["solana","base"]}}],"responses":{"200":{"description":"The token list.","content":{"application/json":{"schema":{"type":"object","required":["tokens"],"properties":{"tokens":{"type":"array","items":{"$ref":"#/components/schemas/TokenRow"}}}}}}},"400":{"description":"The query parameters are not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/tokens/recent":{"get":{"operationId":"listRecentTokens","tags":["Tokens"],"summary":"Newly launched tokens","description":"The newest token profiles on one chain, 20 per page, newest first. Pass `nextCursor` back as `cursor` for the next page; it is null on the last page. Rate limit: 90 requests per 60 seconds per IP address.","parameters":[{"name":"chain","in":"query","required":false,"description":"Chain to list.","schema":{"type":"string","enum":["solana","base"],"default":"solana"}},{"name":"cursor","in":"query","required":false,"description":"Offset from a previous `nextCursor`.","schema":{"type":"string","pattern":"^\\d+$"}}],"responses":{"200":{"description":"A page of new tokens.","content":{"application/json":{"schema":{"type":"object","required":["items","nextCursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TokenRow"}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"The query parameters are not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/tokens/{chain}/{address}":{"get":{"operationId":"getToken","tags":["Tokens"],"summary":"Token detail and safety report","description":"Price, market cap, liquidity, 24 hour volume, holder count and the safety report (RugCheck on Solana, GoPlus on Base) for one token. Rate limit: 90 requests per 60 seconds per IP address.","parameters":[{"name":"chain","in":"path","required":true,"description":"Blockchain. Only `solana` is live; `base` answers 404 until Base opens.","schema":{"type":"string","enum":["solana","base"]}},{"name":"address","in":"path","required":true,"description":"Token mint (Solana, base58, 32 to 44 characters) or contract address (Base, 0x plus 40 hex characters).","schema":{"type":"string","minLength":32,"maxLength":44},"example":"DezXAZ8z7PnrnRJjz3wXBoRgixCaDcmt6Hk5YNnXbFmQ"}],"responses":{"200":{"description":"The token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenDetail"}}}},"404":{"description":"Nothing exists at this address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"An upstream market-data provider failed. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tokens/{chain}/{address}/ohlcv":{"get":{"operationId":"getTokenCandles","tags":["Tokens"],"summary":"Price candles","description":"Up to 200 OHLCV candles in USD, oldest first, from the token's deepest pool. Rate limit: 90 requests per 60 seconds per IP address.","parameters":[{"name":"chain","in":"path","required":true,"description":"Blockchain. Only `solana` is live; `base` answers 404 until Base opens.","schema":{"type":"string","enum":["solana","base"]}},{"name":"address","in":"path","required":true,"description":"Token mint (Solana, base58, 32 to 44 characters) or contract address (Base, 0x plus 40 hex characters).","schema":{"type":"string","minLength":32,"maxLength":44},"example":"DezXAZ8z7PnrnRJjz3wXBoRgixCaDcmt6Hk5YNnXbFmQ"},{"name":"interval","in":"query","required":false,"description":"Candle width.","schema":{"type":"string","enum":["1m","5m","15m","1h","4h","1d"],"default":"15m"}}],"responses":{"200":{"description":"The candles.","content":{"application/json":{"schema":{"type":"object","required":["candles"],"properties":{"candles":{"type":"array","items":{"$ref":"#/components/schemas/Candle"}}}}}}},"404":{"description":"Nothing exists at this address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"An upstream market-data provider failed. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tokens/{chain}/{address}/holders":{"get":{"operationId":"getTokenHolders","tags":["Tokens"],"summary":"Top holders","description":"The token's largest holders. Holders who are Murmurn traders are matched to their public profile in `person`. Rate limit: 90 requests per 60 seconds per IP address.","parameters":[{"name":"chain","in":"path","required":true,"description":"Blockchain. Only `solana` is live; `base` answers 404 until Base opens.","schema":{"type":"string","enum":["solana","base"]}},{"name":"address","in":"path","required":true,"description":"Token mint (Solana, base58, 32 to 44 characters) or contract address (Base, 0x plus 40 hex characters).","schema":{"type":"string","minLength":32,"maxLength":44},"example":"DezXAZ8z7PnrnRJjz3wXBoRgixCaDcmt6Hk5YNnXbFmQ"}],"responses":{"200":{"description":"The holders.","content":{"application/json":{"schema":{"type":"object","required":["holders"],"properties":{"holders":{"type":"array","items":{"type":"object","required":["rank","address","amount","percent"],"properties":{"rank":{"type":"integer"},"address":{"type":"string"},"person":{"anyOf":[{"$ref":"#/components/schemas/Person"},{"type":"null"}]},"amount":{"type":"number"},"percent":{"type":"number"},"valueUsd":{"anyOf":[{"type":"number"},{"type":"null"}]}}}}}}}}},"404":{"description":"Nothing exists at this address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"An upstream market-data provider failed. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/leaderboard":{"get":{"operationId":"getLeaderboard","tags":["Traders"],"summary":"Trader leaderboard","description":"Traders ranked by realised plus unrealised profit in USD for the period, 25 per page. Ties share a rank. `me` is null unless the request is signed in. Rate limit: 90 requests per 60 seconds per IP address.","parameters":[{"name":"period","in":"query","required":false,"description":"Ranking window.","schema":{"type":"string","enum":["24h","7d","30d","all"],"default":"7d"}},{"name":"page","in":"query","required":false,"description":"Page number, 1 to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":1}}],"responses":{"200":{"description":"A page of the leaderboard.","content":{"application/json":{"schema":{"type":"object","required":["items","page","pageSize","total"],"properties":{"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Person"},{"type":"object","required":["rank","pnlUsd"],"properties":{"rank":{"type":"integer"},"pnlUsd":{"type":"number"},"winRate":{"type":"integer","minimum":0,"maximum":100}}}]}},"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer","description":"How many traders are ranked for this period."},"me":{"anyOf":[{"type":"object","properties":{"rank":{"anyOf":[{"type":"integer"},{"type":"null"}]},"pnlUsd":{"type":"number"}}},{"type":"null"}]}}}}}},"400":{"description":"The query parameters are not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/traders/{handle}":{"get":{"operationId":"getTrader","tags":["Traders"],"summary":"Public trader profile","description":"A trader's public profile: name, bio, follower counts, lifetime profit, win rate, clan and pinned post. Never includes email or wallet addresses. Rate limit: 90 requests per 60 seconds per IP address.","parameters":[{"name":"handle","in":"path","required":true,"description":"Trader handle, with or without a leading @, case-insensitive.","schema":{"type":"string","pattern":"^@?[A-Za-z0-9_]{3,20}$"}}],"responses":{"200":{"description":"The profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraderProfile"}}}},"404":{"description":"Nothing exists at this address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/traders/{handle}/trust":{"get":{"operationId":"getTraderTrust","tags":["Traders"],"summary":"Trust Score breakdown","description":"The trader's Trust Score (0 to 100) and the parts it is made of, recalculated hourly. `score` is null until the trader has `needed` closed positions. Rate limit: 90 requests per 60 seconds per IP address.","parameters":[{"name":"handle","in":"path","required":true,"description":"Trader handle, with or without a leading @, case-insensitive.","schema":{"type":"string","pattern":"^@?[A-Za-z0-9_]{3,20}$"}}],"responses":{"200":{"description":"The Trust Score.","content":{"application/json":{"schema":{"type":"object","required":["score","closedCount","needed"],"properties":{"score":{"anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"parts":{"anyOf":[{"type":"object","additionalProperties":true,"description":"Each scoring part with its weight and value."},{"type":"null"}]},"washPenalty":{"type":"number"},"closedCount":{"type":"integer"},"needed":{"type":"integer"},"shill":{"type":"object","additionalProperties":true,"description":"Shill Check: how often the trader sold a token before or soon after posting about it."},"computedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}}}}},"404":{"description":"Nothing exists at this address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/scanner":{"get":{"operationId":"getScanner","tags":["Tokens"],"summary":"Newest pools","description":"Up to 100 of the newest liquidity pools, newest first. Rate limit: 90 requests per 60 seconds per IP address.","parameters":[{"name":"chain","in":"query","required":false,"description":"Chain to scan, or `all` for every live chain.","schema":{"type":"string","enum":["solana","base","all"],"default":"all"}}],"responses":{"200":{"description":"New pools.","content":{"application/json":{"schema":{"type":"object","required":["updatedAt","tokens"],"properties":{"updatedAt":{"type":"string","format":"date-time"},"tokens":{"type":"array","items":{"type":"object","required":["chain","address","symbol"],"properties":{"chain":{"$ref":"#/components/schemas/Chain"},"address":{"type":"string"},"symbol":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"logo":{"anyOf":[{"type":"string"},{"type":"null"}]},"priceUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"liquidityUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"fdvUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAtMs":{"anyOf":[{"type":"integer"},{"type":"null"}]}}}}}}}}},"400":{"description":"The query parameters are not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"schemas":{"Chain":{"type":"string","enum":["solana","base"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"What went wrong, as a sentence."},"code":{"type":"string","description":"Stable machine-readable code.","enum":["not_found","rate_limited","region_blocked","not_launched","invalid_request","unauthorized","upstream_unavailable"]},"hint":{"type":"string","description":"What to do about it."},"docs":{"type":"string","format":"uri","description":"Link to the error reference."}}},"Person":{"type":"object","required":["handle"],"properties":{"handle":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"trustScore":{"anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]}}},"TokenRow":{"type":"object","required":["chain","address","symbol"],"properties":{"chain":{"$ref":"#/components/schemas/Chain"},"address":{"type":"string"},"symbol":{"type":"string"},"name":{"type":"string"},"logo":{"anyOf":[{"type":"string"},{"type":"null"}]},"verified":{"type":"boolean"},"priceUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"marketCapUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"change24h":{"anyOf":[{"type":"number","description":"Percent change over 24 hours."},{"type":"null"}]}}},"TokenDetail":{"type":"object","required":["chain","address","symbol","isBlueChip","stale"],"properties":{"chain":{"$ref":"#/components/schemas/Chain"},"address":{"type":"string"},"symbol":{"type":"string"},"name":{"type":"string"},"logo":{"anyOf":[{"type":"string"},{"type":"null"}]},"verified":{"type":"boolean"},"priceUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"marketCapUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"change24h":{"anyOf":[{"type":"number"},{"type":"null"}]},"liquidityUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"volume24hUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"holders":{"anyOf":[{"type":"integer"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"safety":{"anyOf":[{"type":"object","properties":{"level":{"type":"string","enum":["safe","warn","danger","unknown"]},"flags":{"type":"array","items":{"type":"object","additionalProperties":true}},"source":{"type":"string","enum":["rugcheck","goplus"]},"checkedAt":{"type":"string","format":"date-time"}}},{"type":"null"}]},"isBlueChip":{"type":"boolean","description":"Blue-chip tokens trade at the lower 0.25% platform fee."},"stale":{"type":"boolean","description":"True when the market numbers could not be refreshed and are older than usual."},"pairAddress":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"Candle":{"type":"object","required":["t","o","h","l","c","v"],"properties":{"t":{"type":"integer","description":"Open time, Unix milliseconds."},"o":{"type":"number"},"h":{"type":"number"},"l":{"type":"number"},"c":{"type":"number"},"v":{"type":"number","description":"Volume in USD."}}},"TraderProfile":{"allOf":[{"$ref":"#/components/schemas/Person"},{"type":"object","required":["followers","following","joinedAt"],"properties":{"bannerUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"bio":{"anyOf":[{"type":"string"},{"type":"null"}]},"xHandle":{"anyOf":[{"type":"string"},{"type":"null"}]},"followers":{"type":"integer"},"following":{"type":"integer"},"pnlUsd":{"type":"number"},"pnlPct":{"anyOf":[{"type":"number"},{"type":"null"}]},"winRate":{"anyOf":[{"type":"number"},{"type":"null"}]},"joinedAt":{"type":"string","format":"date-time"},"clan":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tag":{"type":"string"}}},{"type":"null"}]},"pinned":{"anyOf":[{"type":"object","additionalProperties":true,"description":"The trader's pinned post."},{"type":"null"}]}}}]},"PublicStats":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean"},"traders":{"type":"integer"},"trades24h":{"type":"integer"},"volume24hUsd":{"type":"number"},"activity":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"usd":{"type":"number"},"symbol":{"type":"string"},"trustTier":{"type":"string","enum":["gold","other"]},"at":{"type":"string","format":"date-time"}}}}}}},"responses":{"RateLimited":{"description":"Too many requests from this IP address. Wait `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"The quota, e.g. `\"market\";q=90;w=60` (90 requests per 60 seconds).","schema":{"type":"string"}},"RateLimit":{"description":"What is left, e.g. `\"market\";r=0;t=60` (0 left, resets within 60 seconds).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}