Documentation

1 Getting Started

Getting started on hopium.trade takes less than two minutes. No wallet extensions, no seed phrases to manage — just your X (Twitter) account and some SOL.

Step 1: Connect with X

Click the "Connect with X" button on the landing page. You'll be redirected to Twitter's OAuth screen where you authorize hopium.trade to read your basic profile information (username and avatar). After approval, you're redirected back to the app and automatically signed in.

Behind the scenes, the server creates a secure session cookie (httpOnly, SameSite=Strict) that identifies you on subsequent requests. A unique Ed25519 keypair is generated server-side to serve as your personal Solana deposit wallet. This keypair is encrypted and stored — you never need to manage it directly.

Step 2: Deposit SOL

Once connected, click the wallet icon in the top bar to open the Deposit modal. You'll see your personal Solana deposit address displayed as both a copyable string and a QR code. Send SOL from any Solana-compatible wallet — Phantom, Solflare, Backpack, Sollet, or any wallet that supports SPL transfers. There is no minimum deposit, but your balance must cover at least a $1 bet to start playing.

Step 3: Place Your First Bet

Navigate to the trading grid by selecting an asset (BTC, ETH, BNB, or SOL). You'll see a scrollable grid of cells with multipliers. Click any cell, set your bet amount using the slider ($1–$10), and confirm. Your bet appears on the grid immediately and will settle automatically within seconds.

Troubleshooting

• "Connect with X" not working? Make sure pop-ups are enabled in your browser. Twitter's OAuth flow opens in a redirect — ad blockers or strict privacy settings can interfere. Try disabling extensions temporarily or use an incognito window.
• Stuck on a loading screen? Hard-refresh the page (Ctrl+Shift+R or Cmd+Shift+R). If the issue persists, clear cookies for hopium.trade and reconnect.
• Deposit not showing up? Double-check you sent SOL (not an SPL token) to the correct address. Deposits are polled every ~10 seconds, so wait at least 30 seconds. See the Deposits & Withdrawals section for more troubleshooting.
• Using a mobile wallet? Copy your deposit address and paste it into your wallet's send screen. QR code scanning also works with most mobile wallets including Phantom and Solflare.

2 How the Grid Works

The grid is the core of hopium.trade — a real-time, interactive visualization of price movement where every cell represents a potential bet.

The Price Feed

Price data is sourced in real-time from CoinGecko's API. The server polls the latest spot price for each supported asset and broadcasts updates to all connected clients via WebSocket. This means every user sees the same price at the same time, with minimal latency. The price feed refreshes multiple times per second to ensure the grid stays current with live market conditions.

The Price Line

A horizontal price line stretches across the grid, representing the current market price of the selected asset. As the real price moves up or down, the price line shifts vertically on the grid in real-time. This line is the reference point for all bets — cells above it represent higher price targets, cells below represent lower ones.

Grid Dimensions & Viewport

The grid is a large two-dimensional space divided into uniformly sized cells. Only a portion of the grid is visible at any time — you scroll vertically to explore cells at different price levels and horizontally across the time axis. The viewport automatically adjusts so the price line stays in view, but you can freely scroll to explore other areas.

How Multipliers Are Calculated

Each cell's multiplier is determined by its distance from the current price line. Cells near the price line have low multipliers (close to 1.01x) because they're likely to be hit. Cells far from the price line have high multipliers (up to 100x or more) because the price would need to move significantly to reach them. The multiplier directly represents the payout ratio: a 5x multiplier on a $2 bet returns $10 if you win.

Cell Colors & Visual Indicators

• Green-shaded cells are near the current price and have lower multipliers — these are high-probability, lower-reward bets.
• Darker / further cells carry higher multipliers and represent riskier, higher-reward positions.
• Highlighted cells indicate where your active bets are placed.
• The price line itself glows to clearly separate "above price" from "below price" regions.

Auto-Follow Camera

By default, the grid viewport automatically follows the price line as it moves — this is the auto-follow camera. It keeps the action centered so you never lose sight of the most relevant cells. If you manually scroll away, auto-follow pauses. It resumes when the price line moves back into view or when you click to re-center.

3 Deposits & Withdrawals

Deposit Flow

When you create an account, the system generates a dedicated Solana deposit wallet just for you. This address is permanent and unique — every SOL transaction sent to it is credited to your hopium.trade balance.

• Open the Deposit modal by clicking the wallet icon in the top navigation bar.
• Copy your deposit address or scan the QR code with your mobile wallet.
• Send SOL from any Solana wallet (Phantom, Solflare, Backpack, or any SPL-compatible wallet).
• Wait for confirmation. Solana transactions typically confirm in under 1 second, but the platform polls for new deposits approximately every 10 seconds. Your balance will update within 10–20 seconds of a confirmed transaction.

How Balance Sync Works

The server runs a background process that queries the Solana blockchain for new incoming transactions to your deposit address. This polling happens on a ~10 second interval. When a new deposit is detected, the SOL amount is converted to USD at the current market rate and added to your in-app balance. There is no manual "confirm deposit" step — it's fully automatic.

Withdrawal Process

• Open the Withdraw tab in the wallet modal.
• Set your withdrawal address — this is the Solana wallet where you want to receive funds. You can change this at any time.
• Enter a USD amount to withdraw. The equivalent SOL amount is calculated at the current rate.
• Submit the request. The platform sends SOL from your deposit wallet to your specified withdrawal address. This transaction is on-chain and verifiable on any Solana block explorer.

The 5-Minute Withdrawal Lock

After placing a bet, withdrawals are locked for 5 minutes. This cooldown prevents abuse scenarios where a user could bet and immediately withdraw before settlement completes. The timer resets with each new bet. You can see the remaining lock time in the Withdraw tab. Once the timer expires, withdrawals are available instantly.

Gas Fees

Solana network fees (commonly called "gas") are extremely low — typically 0.000005 SOL per transaction (fractions of a cent). These fees are deducted from the transaction amount during withdrawals. Deposits do not incur any platform fees, though your sending wallet will pay the standard Solana network fee.

Minimum Withdrawal

There is a minimum withdrawal amount to ensure the transaction covers Solana's base network fee. Withdrawals below this threshold will be rejected with a clear error message.

Deposit Troubleshooting

• Deposit not showing after 30 seconds? Verify the transaction on a Solana block explorer (like Solscan or Solana Explorer) using your deposit address. If the transaction is confirmed on-chain but not reflected in your balance, try refreshing the page.
• Sent the wrong token? hopium.trade only accepts native SOL. SPL tokens sent to your deposit address cannot be credited and may be unrecoverable.
• Sent from an exchange? Some exchanges batch withdrawals and may take longer to broadcast. Wait for the exchange to confirm the transaction, then allow 10–20 seconds for balance sync.
• Still not showing? Contact support with your deposit address and the transaction signature (txid) for manual investigation.

4 Betting

Betting on hopium.trade is designed to be fast, simple, and transparent. Every bet follows a deterministic lifecycle and settles automatically — no manual intervention required.

Placing a Bet

• Click any cell on the grid to select your target price level.
• Set your amount using the slider or input field. Bet amounts range from $1 to $10 per bet.
• Confirm the bet. Your balance is immediately debited and the bet appears on the grid as an active position.

Bet Lifecycle

Every bet moves through a clear state machine:

• OPEN — The bet is live and waiting for the price to move. The grid cell is highlighted showing your active position.
• LOST — The settlement window closed and the price line did not reach your cell. Your bet amount is forfeited. Transition: OPEN → LOST.
• PENDING — The price line hit your cell and you won. The payout is being processed on-chain. Transition: OPEN → PENDING.
• WON — The on-chain payout transaction has been confirmed. Your winnings have been sent to your deposit wallet. Transition: PENDING → WON.

How Settlement Works

Settlement is fully automatic and server-side. The server continuously compares the live price feed against all open bets. When a bet's settlement conditions are met (either the price reached the target cell or the settlement window expired), the server updates the bet status immediately. There is no manual "claim" step.

Payout Process

When you win a bet, the treasury wallet initiates a Solana transaction sending the payout amount directly to your deposit wallet. This happens automatically within seconds of settlement. The payout equals your bet amount multiplied by the cell's multiplier, minus a small platform fee. You can see the transaction on any Solana block explorer.

What Affects Your Win Probability

• Multiplier — Higher multipliers mean the price needs to move further to reach your cell, making a win less likely but more rewarding.
• House edge — A small mathematical edge is built into the multiplier calculation. This is how the platform sustains itself. The edge is consistent and transparent across all cells.
• Market volatility — More volatile assets have faster-moving price lines, which can increase the chance of hitting distant cells.

Bet Amount Limits

Each individual bet must be between $1 and $10. You can have multiple active bets simultaneously across different cells and different assets. Your total exposure is limited by your available balance.

Rate Limiting

To ensure fair play and server stability, bets are rate-limited to 1 bet per second per user. If you attempt to place bets faster than this, the excess requests will be rejected with an error message. This prevents automation abuse and ensures the platform remains responsive for all users.

Network Issues During Betting

If your connection drops while a bet is active, the bet continues to live on the server. Settlement happens server-side regardless of your connection state. When you reconnect, your bet history and current positions will sync automatically. If a payout fails due to Solana network congestion, the system retries automatically until the transaction confirms.

5 Supported Assets

hopium.trade currently supports four major crypto assets. Each asset has its own independent grid, price feed, and betting pool.

BTC — Bitcoin

The original cryptocurrency and the largest by market capitalization. Bitcoin's price tends to move in larger absolute increments due to its high unit price, which creates a wide spread of multiplier levels on the grid. BTC is ideal for traders who prefer more measured price action with occasional sharp moves.

ETH — Ethereum

The leading smart contract platform. Ethereum's price is typically more volatile than Bitcoin in percentage terms, resulting in a faster-moving price line on the grid. ETH grids tend to see more frequent cell hits, making it popular among active traders.

BNB — BNB Chain

The native token of the BNB Chain ecosystem. BNB offers moderate volatility and a well-established price feed. It provides a middle ground between the stability of BTC and the volatility of smaller-cap assets.

SOL — Solana

The native token of the Solana blockchain — the same chain that powers hopium.trade's deposit and withdrawal system. SOL is known for its higher volatility, which creates more dynamic grid movement and more opportunities for high-multiplier hits.

Price Feed Details

All price data is sourced from CoinGecko's API, one of the most widely used and reliable crypto price aggregators. Prices are refreshed in real-time via server-side polling and broadcast to clients over WebSocket connections. Each asset's price feed operates independently, ensuring that congestion on one feed doesn't affect others.

Coming Soon: HOPIUM Token

The HOPIUM token is on the roadmap as a future supported asset. Once launched, HOPIUM will have its own grid and may include special features exclusive to token holders. Stay tuned for announcements on launch timing and token utility.

6 Leaderboard

The leaderboard ranks traders by performance and updates in real-time as bets settle. It's a competitive snapshot of who's generating the most profit on the platform.

Ranking Algorithm

Traders are ranked by realized PnL (Profit and Loss) in descending order. Realized PnL is calculated as the sum of all winnings from WON bets minus the sum of all amounts lost from LOST bets. Only fully settled bets count — OPEN and PENDING bets are not included in the ranking calculation.

What Counts as Realized

• WON bets — The payout amount (bet × multiplier) minus the original bet amount is added to your realized PnL as profit.
• LOST bets — The full bet amount is subtracted from your realized PnL as a loss.
• OPEN / PENDING bets — These are excluded from the ranking until they reach a terminal state (WON or LOST).

Stats Breakdown

• Win Rate — The percentage of your settled bets that resulted in a win (WON ÷ total settled × 100).
• Volume — The total USD value of all bets you've placed, regardless of outcome.
• Positions — The number of currently open (active) bets.
• Trades — The total number of bets placed across your account lifetime.

Top 3 Spotlight vs. Top 20 Table

The leaderboard UI features two tiers. The top 3 traders are displayed in a prominent spotlight section with larger cards showing their avatar, username, PnL, and key stats. Below that, a top 20 table lists the next tier of traders in a compact row format with sortable columns. This design highlights the best performers while still giving recognition to a broader group of skilled traders.

Update Frequency

The leaderboard updates in real-time. Every time a bet settles (transitions to WON or LOST), the affected trader's stats are recalculated and the ranking order is refreshed. There is no caching delay — what you see is the current state.

7 Security

Security is foundational to hopium.trade. From wallet architecture to API design, every layer is built to protect user funds and data.

Deposit Wallet Architecture

Each user is assigned a dedicated Ed25519 keypair on the Solana blockchain. This keypair is generated server-side at account creation and serves as your personal deposit wallet. The public key is your deposit address; the private key is never exposed to the client or stored in plaintext.

Private Key Encryption

All private keys are encrypted at rest using Fernet symmetric encryption (AES-128-CBC with HMAC-SHA256 authentication). The encryption key is managed server-side and is not stored alongside the encrypted keypairs. This means that even if the database were compromised, the private keys would remain unreadable without the separate encryption key. No plaintext private keys are ever stored in the database, logs, or any persistent storage.

Session & Cookie Security

• httpOnly — Session cookies cannot be accessed by client-side JavaScript, preventing XSS-based session theft.
• Secure flag — Cookies are only transmitted over HTTPS connections, preventing interception over unencrypted channels.
• SameSite=Strict — Cookies are not sent with cross-origin requests, mitigating CSRF attacks.

Authentication Flow

Authentication uses a nonce-based OAuth flow with X (Twitter). A unique, time-limited nonce is generated for each login attempt and validated on callback. This prevents replay attacks and ensures each authentication request is genuine. Sessions expire after a configurable period of inactivity.

Rate Limiting

All API endpoints are protected by rate limiting. Betting endpoints enforce a 1-request-per-second limit per user. Authentication, deposit, and withdrawal endpoints have their own rate limits to prevent brute-force attacks and abuse. Exceeding rate limits returns a 429 status code with a clear error message.

CORS Policy

The server enforces a strict Cross-Origin Resource Sharing (CORS) policy that only allows requests from the official hopium.trade domain. This prevents unauthorized third-party websites from making API calls on behalf of users.

HTTPS Enforcement

All traffic to and from hopium.trade is encrypted via HTTPS (TLS 1.2+). HTTP requests are automatically redirected to HTTPS. This ensures that all data in transit — including session tokens, wallet addresses, and transaction data — is protected from eavesdropping and man-in-the-middle attacks.

On-Chain Transparency

All payouts and withdrawals are executed as standard Solana transactions, visible on any public block explorer. This provides a verifiable, tamper-proof record of every fund movement on the platform.

? FAQ