# PopularityX Beta Documentation (full text) > These are the docs for the PopularityX CLOSED BETA: invite-only, running on testnet with practice money, so nothing is at stake and nothing is promised. PopularityX itself is the market that prices who matters in crypto: a board of names, each with a live price in cents, summing to $1.00. Everyone in the beta starts with the same $10,000 practice stack, trades the board by hand or with bots, and earns $POPX on the value of what they hold. Being early pays. This file is the complete text of the PopularityX beta documentation at https://betadocs.popularityx.com, concatenated into one document. It is generated from the published pages on every deploy, so it always matches the live site. Canonical URLs: - https://betadocs.popularityx.com/llms-full.txt (this file, the full beta rundown) - https://betadocs.popularityx.com/llms.txt (the short index) - https://betadocs.popularityx.com (the human beta docs) - https://docs.popularityx.com/llms-full.txt (the FINAL PRODUCT docs as one file: what PopularityX is beyond the beta) - https://docs.popularityx.com/llms.txt (the product docs index) Generated: 2026-08-25 ---------------------------------------------------------------- PAGE: Welcome URL: https://betadocs.popularityx.com/ ---------------------------------------------------------------- # Welcome to the beta PopularityX is a live market on who matters most in crypto. This is the closed beta: invite-only, running on testnet with practice money, so nothing is at stake and nothing is promised. Everyone starts with the same $10,000 stack and trades the board of names. [Enter the app](https://app.popularityx.com/join) The beta is invite-only, so you join with a code from a member. No invite yet? [Join the waitlist on Telegram](https://t.me/+8zbgI8J-Y_ozYzU8) and we will get you in. Here is what you are walking into: - **Everyone starts equal.** The moment you join, your account is credited with $10,000 of practice money. Same stack for everyone, so the leaderboard is pure skill. - **Trade the board.** Go Long on a name you think is underrated, Short on one you think is overrated. Prices move as players back their picks. - **Being early pays.** You earn $POPX on the value of your positions over time, and $POPX earning is weighted toward the earliest players. The beta sits at the very front of that curve. The board, name detail pages, and the leaderboard are open to look at without an invite. The invite is what lets you act: trade, hold a bankroll, keep a portfolio, and build a record. These pages cover the beta. For what PopularityX is and how the full product works, see [the full docs](https://docs.popularityx.com). ## Explore the beta - [House Rules](https://betadocs.popularityx.com/house-rules): Equal stacks, be decent, and how the game is meant to feel. - [Running a Bot](https://betadocs.popularityx.com/bots): Point a bot at your account. Bots are welcome and trade as you. - [FAQ](https://betadocs.popularityx.com/faq): Invites, wallets, practice money, and $POPX, answered. - [Community](https://betadocs.popularityx.com/community): The Telegram: the waitlist, the help desk, and the room. Want the full mechanics of the board, prices, and $POPX? The system docs go deep at [docs.popularityx.com](https://docs.popularityx.com). ---------------------------------------------------------------- PAGE: House Rules URL: https://betadocs.popularityx.com/house-rules ---------------------------------------------------------------- # House rules The beta is small and friendly. There is not much to enforce, because the earning system does the work: you earn $POPX on the value of your positions over time, so there is no edge in gaming activity. The rules below are mostly about how the game is meant to feel. ## Everyone starts equal Every account starts with the same $10,000 of practice money, granted silently the moment you join. There is no way to top up and nothing to deposit. Equal stacks are the point: the leaderboard measures skill, not who arrived with more. ## Be decent This is a community of people betting on people. Trade hard, talk trash if you like, but keep it good-natured. The [Telegram](https://betadocs.popularityx.com/community) is the room; treat it like one. ## Bots are welcome Running a bot is a normal way to play. It is not a loophole and it is not frowned upon. See [Running a Bot](https://betadocs.popularityx.com/bots) for how, and the points below for what it does and does not change. - **Your bot trades as you.** Every trade it makes appears on the public tape under your @handle. - **Its performance is your performance.** Bot trading counts on the leaderboard exactly like a trade made by hand. - **Earning is the same.** $POPX is earned on the value of your positions over time, by bot or by hand. ## One account, one stack You can add wallets you control and split your stack across them however you like, but the total is still one $10,000 stack per account. Splitting activity across wallets does not create more money and does not earn more $POPX: value and $POPX roll up to your name no matter how many wallets you run. Every wallet trades as you. ## The shape of the game The board is zero-sum minus fees: every dollar won is a dollar another trader put there. $POPX flows fastest to the wave-riders, because it is earned on the value of your positions over time and weighted toward the earliest eras, so the biggest earners are the traders riding the most value while the game runs. And the whole board is the other side of any pump: prices sum to $1.00, so pushing a name up makes every other position a short against you. All of it in practice money, with nothing at stake. ## Nothing is at stake This is testnet with practice money. Nothing you do in the beta can cost you anything, and nothing is promised. Play freely, take the trades you would be scared to take with real money, and tell us what breaks. ---------------------------------------------------------------- PAGE: Running a Bot URL: https://betadocs.popularityx.com/bots ---------------------------------------------------------------- # Running a bot Running a bot is a normal way to play the beta. Everything a bot needs is a private key and HTTP access, and its trades count exactly like trades made by hand: they appear on the public tape under your @handle and they move the leaderboard the same way. This page is the short version. The full technical guide, with endpoints, signing, and the trade flow, is the [Bot Guide](https://betadocs.popularityx.com/bot-guide). ## The idea You join the beta as a person, and then point a bot at your account. There is no separate bot signup and no bot species: a wallet trading is you trading, whether you drive it by hand or with code. - **Join first.** Get in through the [invite door](https://app.popularityx.com/join) and sign in with X like any other player. - **Give the bot a key.** Add a wallet you control to your account and let the bot sign with it, or export your app wallet's key. Either way the wallet is bound to your @handle. - **Fund it from your stack.** Move some of your $10,000 to the bot's wallet. There is one stack per account no matter how many wallets you run. - **Trade.** The bot reads prices and submits signed orders. A relayer covers the gas, or the bot can manage its own. ## Good to know - **Volume earns nothing.** You earn $POPX on the value of your positions over time, so there is no point wash trading. Be right, not busy. - **One stack, many wallets.** Splitting your bankroll across bots does not create more money and does not earn more $POPX. Value and $POPX roll up to your name. - **Keys are stacks.** Whoever holds a wallet's key controls its balance. Keep keys off shared machines, out of source control, and out of logs. Ready for the details? Head to the [Bot Guide](https://betadocs.popularityx.com/bot-guide) for the endpoints, the signing scheme, and the mental model. ---------------------------------------------------------------- PAGE: Bot Guide URL: https://betadocs.popularityx.com/bot-guide ---------------------------------------------------------------- # Bot Guide This is the technical guide to running a bot against PopularityX. Everything a bot needs is a private key and HTTP access: reads are plain RPC calls, trades are signed orders that a relayer submits and pays gas for, and there is a direct on-chain path if you would rather manage your own gas. New to the beta? Start at [Welcome](https://betadocs.popularityx.com/). For the short, non-technical version of running a bot, see [Running a Bot](https://betadocs.popularityx.com/bots). ## Giving your bot a key Your account holds a stack of eUSDC on your app wallet, and every wallet you add maps back to your @handle, so the tape and the leaderboard attribute all of it to you. For how accounts and the beta stack work, see the [House Rules](https://betadocs.popularityx.com/house-rules). To trade, a bot needs a private key it can sign with, and some eUSDC on the wallet that key controls. There are two ways to give it a key. ### Option A: link an external wallet In the wallet panel you can link external wallets to your account (up to 3). Link a wallet you generated yourself, and give your bot that key. The linked wallet shows up on the tape under your @handle like your app wallet does. The stack lives on your app wallet, so move some of it over: eUSDC is a standard ERC20, and a plain `transfer` to the bot wallet moves tradeable balance. The bot then trades its own balance with its own key. This is the recommended setup. The key never leaves the machine that generated it, and the bot only ever holds the balance you gave it. ### Option B: export your app wallet's key The app wallet is a Privy embedded wallet, and Privy supports exporting its private key from the wallet panel. A bot holding that key trades your full stack directly. Be sober about what this means. Whoever holds that key controls the wallet: the whole stack, not a budget you set. Export it only onto a machine you control, keep it out of source control, logs, and shell history, and prefer Option A if you plan to run anything you did not write yourself. Treat a leaked key as a lost stack. ## Network and endpoints Everything runs on Robinhood Chain testnet. | Thing | Value | |---|---| | Chain | Robinhood Chain testnet, `chainId 46630` | | RPC | `https://rpc.testnet.chain.robinhood.com` | | Explorer | `https://explorer.testnet.chain.robinhood.com` | | Ledger (entry point, reads, EIP-712 verifying contract) | `0xB2E4833C2126A0390eDf43De6aeB7eBF90c1De34` | | LedgerViews (aggregated snapshots) | `0xEEef132a22887bce3d820e7f065d0Be220625efd` | | eUSDC token | `0x424c1b50462c98FdE7d6a2e8E41069A0a8DBe342` | | Relayer base URL | `https://app.popularityx.com/relayer` | Relayer endpoints, all under the base URL: | Endpoint | What it does | |---|---| | `POST /relay` | Submit a signed `BuyOrder` (gasless trade) | | `GET /history?marketId=N` | Full per-position price history | | `GET /history/trades?marketId=N` | Recent individual trades | | `GET /health` | Liveness check | ## The mental model - The unit of account is eUSDC, shown in the app as dollars. Balances and trade amounts are 1e6 fixed point, so $1 is `1_000_000`. - A board contains a fixed roster of positions. Each position has a Long token and a Short token. - Prices are 1e18 WAD. A Long price of `0.05` means the market assigns that position a 5% share of the board, and one Long token costs 0.05. Short price is always `1 - long`. - At the contract level everything is a buy. To reduce or reverse a position you buy the opposite side: Long and Short cancel when they arrive in the same wallet, releasing collateral. The app presents this as selling; a bot just buys the other token. To cash out, `withdraw` free collateral. - Gasless orders use a sequential per-trader nonce: one in-flight order at a time. Enumerate boards and positions at runtime rather than hardcoding them. `getMarkets()` on the Ledger is the source of truth. The flagship Crypto Influencers board is `marketId 1`, with one position per influencer. On-chain a position is identified by its numeric position id; the X handle you see in the app is the roster's display mapping for that id, so key on the id, not the handle, and a handle change does not change the position. Board and position creation is permissioned. Bots trade existing boards; to request a new board or position, ask the team. ## Reading the board All reads are `view` calls against the RPC. Prices in WAD (1e18), amounts in 1e6. On the Ledger: ```solidity function getMarkets() view returns (uint256[]) function getMarketPositions(uint256 marketId) view returns (uint256[]) function getPricingMM(uint256 marketId) view returns (address) function metaNonces(address trader) view returns (uint256) function realFreeCollateral(address account) view returns (uint256) ``` On the pricing MM (address from `getPricingMM`): ```solidity function getLongPriceWad(uint256 marketId, uint256 positionId) view returns (uint256) function getShortPriceWad(uint256 marketId, uint256 positionId) view returns (uint256) function previewBuyForUSDCFull(uint256 marketId, uint256 positionId, bool isLong, uint256 usdcIn) view returns (FullVectorPreview) // .amount = tokensOut for usdcIn ``` On LedgerViews, one call for a whole board: ```solidity function getMarketSnapshot(uint256 marketId) returns (MarketInfo m, PositionInfoExtended[] infos) function getMarketSnapshotForAccount(uint256 marketId, address account) returns (MarketInfo m, PositionInfoWithBalanceExtended[] infos) // adds .balance per token ``` `infos` has `2*n` entries for `n` positions: index `2*i` is Long, `2*i+1` is Short. ```js const { ethers } = require("ethers"); const provider = new ethers.JsonRpcProvider("https://rpc.testnet.chain.robinhood.com"); const LEDGER = "0xB2E4833C2126A0390eDf43De6aeB7eBF90c1De34"; const ledger = new ethers.Contract(LEDGER, [ "function getMarkets() view returns (uint256[])", "function getPricingMM(uint256) view returns (address)", "function metaNonces(address) view returns (uint256)", "function realFreeCollateral(address) view returns (uint256)", ], provider); const mm = new ethers.Contract(await ledger.getPricingMM(1n), [ "function getLongPriceWad(uint256,uint256) view returns (uint256)", ], provider); const longWad = await mm.getLongPriceWad(1n, 2n); console.log("Long price:", Number(longWad) / 1e18); // e.g. 0.05 ``` The price history endpoint (`/history?marketId=1`) and the trades feed (`/history/trades?marketId=1`) give you movement and momentum without scanning chain events. ## Placing a trade (gasless) Build a `BuyOrder`, sign it with EIP-712, POST it to the relayer. The relayer simulates, batches, submits, and pays gas. The position is credited to the signer, never the relayer. The signing domain is a protocol constant: ```js const DOMAIN = { name: "Sentidex-Ledger", // protocol-level constant, exact string required version: "1", chainId: 46630, verifyingContract: "0xB2E4833C2126A0390eDf43De6aeB7eBF90c1De34", // Ledger }; const TYPES = { BuyOrder: [ { name: "trader", type: "address" }, { name: "marketId", type: "uint256" }, { name: "positionId", type: "uint256" }, { name: "isLong", type: "bool" }, { name: "usdcIn", type: "uint256" }, { name: "minTokensOut", type: "uint256" }, { name: "nonce", type: "uint256" }, { name: "deadline", type: "uint256" }, ] }; ``` ```js const RELAYER_BASE = "https://app.popularityx.com/relayer"; const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider); async function buy({ marketId, positionId, isLong, usdcIn, slippageBps = 300 }) { const mm = new ethers.Contract(await ledger.getPricingMM(marketId), [ "function previewBuyForUSDCFull(uint256,uint256,bool,uint256) view returns (tuple(uint256 amount,uint256[] a,uint256[] b,uint256[] c,uint256 d,uint256 e,uint256 f,uint256 g))", ], provider); const expected = (await mm.previewBuyForUSDCFull(marketId, positionId, isLong, usdcIn)).amount; const minTokensOut = expected * BigInt(10_000 - slippageBps) / 10_000n; const order = { trader: wallet.address, marketId: BigInt(marketId), positionId: BigInt(positionId), isLong, usdcIn: BigInt(usdcIn), minTokensOut, nonce: await ledger.metaNonces(wallet.address), deadline: BigInt(Math.floor(Date.now() / 1000) + 600), }; const signature = await wallet.signTypedData(DOMAIN, TYPES, order); const res = await fetch(`${RELAYER_BASE}/relay`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ order: { trader: order.trader, marketId: order.marketId.toString(), positionId: order.positionId.toString(), isLong: order.isLong, usdcIn: order.usdcIn.toString(), minTokensOut: order.minTokensOut.toString(), nonce: order.nonce.toString(), deadline: order.deadline.toString(), }, signature, }), }); const data = await res.json(); if (!res.ok) throw new Error(data.error || `relay ${res.status}`); return data; // { txHash, included } } ``` Response handling: | Response | Meaning | Action | |---|---|---| | `{ txHash, included: true }` | Filled. Position credited, nonce advanced. | Next order. | | `{ txHash, included: false }` | Batched but skipped on-chain (slippage or solvency). Nonce did not advance. | Re-quote, re-sign with a looser `minTokensOut`. | | `409 { error: "stale nonce: ..." }` | Your nonce does not match the chain. | Re-read `metaNonces`, retry. | | `4xx { error }` | Bad signature, expired, or malformed. | Fix and re-sign. | Rules of the road: - One in-flight order per wallet. Wait for `included: true` or a fresh `metaNonces` before the next. - `usdcIn` must not exceed the wallet's `realFreeCollateral`. - `isLong: false` buys the Short token. Same struct, same flow. - Always set a slippage floor. `minTokensOut: 0` accepts any fill. ## Placing a trade (own gas) If your bot wallet holds testnet ETH it can skip the relayer and call the Ledger directly. No EIP-712, no per-trader nonce coordination; the wallet submits the transaction, pays gas, and the position is credited to `msg.sender`. The same eUSDC balance is spent either way, so a bot can mix both paths. ```solidity function buyForMarket(uint256 marketId, uint256 positionId, bool isLong, uint256 usdcIn, uint256 minTokensOut) external function buyExactTokensForMarket(uint256 marketId, uint256 positionId, bool isLong, uint256 t, uint256 maxUSDCIn) external ``` On a bad trade this path reverts instead of returning `included: false`; catch the revert, re-quote, retry. If your bot wallet needs gas, ask the team. ## Reading back a position ```solidity // LedgerViews: balances for every Long/Short token in a board, one call getMarketSnapshotForAccount(marketId, account) // .infos[i].balance, .isLong // Ledger: net view of one position getPositionLiquidity(account, marketId, positionId) ``` Testnet values only. The stack is test eUSDC with no real value, which is exactly why the beta is the right place to prove a strategy. ---------------------------------------------------------------- PAGE: FAQ URL: https://betadocs.popularityx.com/faq ---------------------------------------------------------------- # FAQ Common questions from beta testers. If yours is not here, ask in the [Telegram](https://betadocs.popularityx.com/community). ### How do I get an invite? Invites come from members, who each hold a few codes to hand out. A code arrives as a link with `?i=` in it, or as a code you can type on the door. If you do not know a member yet, join the [Telegram](https://betadocs.popularityx.com/community) waitlist. ### Is any of this real money? No. The beta runs on testnet with practice money. Everyone starts with the same $10,000 stack, granted the moment you join. Nothing is at stake, nothing is promised, and nothing you do can cost you anything. ### Do I need a wallet, or crypto, to join? No. You sign in with X and you are your handle. The account is set up for you and the $10,000 is credited silently. You never have to see a wallet address to play. ### What is $POPX? $POPX is the record your account earns. It accumulates on the value of everything your account holds, positions and cash, over time, and it never goes down. You earn $POPX on the value of your positions over time; there is nothing to stake and nothing to click. $POPX is the governance token of the protocol and nothing else is promised. The full explanation is in the [docs](https://docs.popularityx.com/pop). ### How do I climb the leaderboard? The leaderboard ranks members by $POPX earned. Your earn rate at any moment is your account value, so the way up is to grow your account and keep it high: be right about who rises and falls, and be early. Volume alone does nothing. ### Can I run a bot? Yes, and it is encouraged. Running a bot is a normal way to play. See [Running a Bot](https://betadocs.popularityx.com/bots) for the short version and the [Bot Guide](https://betadocs.popularityx.com/bot-guide) for the full technical guide. ### Can I have more than one account? One person, one name. You can add several wallets to your one account and split your stack across them, but there is one $10,000 stack and one record per member. Value and $POPX roll up to your name however many wallets you run. ### Why can I see the board without signing in? The board, name detail pages, and the leaderboard are public: the live market is the point, and you should be able to look before you join. Signing in with an invite is what lets you act, trade, hold a bankroll, keep a portfolio, and build a record. ### Can I deposit or withdraw? Not in the beta. The stack is closed-loop practice money by design. Deposits and withdrawals arrive as a first-class feature when real money does. ### Where do I report a bug or ask for help? The [Telegram](https://betadocs.popularityx.com/community) is the room. Post what you saw and how to reproduce it. Breaking things is useful; that is what the beta is for. ---------------------------------------------------------------- PAGE: Community URL: https://betadocs.popularityx.com/community ---------------------------------------------------------------- # Community The beta lives on Telegram. It is the waitlist, the help desk, and the room where players talk. ## Telegram Join here: [t.me/+8zbgI8J-Y_ozYzU8](https://t.me/+8zbgI8J-Y_ozYzU8) It is the one place to be. Use it to: - **Get on the waitlist** if you do not have an invite yet. Members hold codes to hand out; the scarcity is how the beta grows. - **Ask for help** with joining, trading, or running a bot. - **Report bugs.** Post what you saw and how to reproduce it. Breaking things is useful. - **Talk about the board.** Argue about who matters. That is the whole game. ## Follow along - **X:** [@popularity_x](https://x.com/popularity_x) - **App:** [app.popularityx.com](https://app.popularityx.com) - **Docs:** [docs.popularityx.com](https://docs.popularityx.com) Be decent to each other. Trade hard, talk your book, keep it good-natured.