Documentation

1 Getting Started

Getting started takes about two minutes: an EVM wallet (MetaMask works), the Ethereum network, and some ETH on Ethereum.

Step 1: Connect with X

Click Connect wallet. Your wallet is asked to switch to (or add) Ethereum, then to sign a short login message. The signature costs no gas and moves no funds — it only proves you own the address.

Behind the scenes, the server creates a secure session cookie (httpOnly, SameSite=Lax) and generates a unique EVM keypair that serves as your personal deposit wallet on Ethereum. The key is encrypted at rest; you never handle it directly.

Step 2: Deposit ETH

Once connected, click Deposit in the top bar. You'll see your personal deposit address and a one-click Send from wallet button that transfers ETH straight from MetaMask. There is no minimum deposit, but your balance must cover at least a $1 bet plus a sliver of gas.

Step 3: Place Your First Bet

Pick an asset (BTC, ETH, BNB or SOL) in the top bar. The whole screen is the grid: set your amount in the bottom-left panel, then tap any cell ahead of the moving line. Your bet appears on the grid immediately and settles automatically when the line reaches that column.

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 dopamine and reconnect.
• Deposit not showing up? Make sure the transfer was on Ethereum (chain id 1), not mainnet. Balances are polled every ~10 seconds.
• Wallet on the wrong network? The app asks MetaMask to switch automatically; if it doesn't, add the network manually with RPC https://ethereum-rpc.publicnode.com and chain id 1.

2 How the Grid Works

The grid is the core of dopamine — 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 (capped at 45x) 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 sign in for the first time, the system generates a dedicated deposit wallet on Ethereum just for you. The address is permanent and unique — any ETH sent to it becomes your in-app 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 ETH from any wallet on Ethereum, or use the in-app Send from wallet button.
• Wait for confirmation. Ethereum blocks land about every 12 seconds, and the platform re-reads balances about every 10 seconds.

How Balance Sync Works

Your in-app balance is the on-chain balance of your deposit wallet (minus stakes that are still confirming), converted to USD at the live ETH price. There is no manual "confirm deposit" step.

Withdrawal Process

• Open the Withdraw tab in the wallet modal.
• Choose a destination — defaults to the wallet you signed in with; any EVM address works.
• Enter a USD amount to withdraw (or press MAX). The equivalent ETH amount is calculated at the current rate.
• Submit the request. The platform sends ETH from your deposit wallet to the destination. The transaction is on-chain and linked to the 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

Bets come out of your in-app balance and cost no gas. Only withdrawals are on-chain transfers, and they pay normal Ethereum network gas.

Minimum Withdrawal

A withdrawal must at least cover its own gas; smaller requests are rejected with a clear error.

Deposit Troubleshooting

• Deposit not showing after 30 seconds? Open the deposit wallet on the explorer (link in the Deposit modal) and check the transfer landed on Ethereum (chain id 1). Then refresh.
• Sent an ERC-20? Only native ETH is credited. Tokens sent to the deposit address are not recognised.
• 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 dopamine 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, the treasury wallet sends the payout to your deposit wallet as a plain transfer on Ethereum, usually within seconds. The payout equals bet × multiplier (the house edge is already inside the multiplier). The transaction hash is linked from your bet row.

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. The price line is generated server-side and settlement replays that same tick history, so what your browser shows is only a preview — the server decides. If a payout fails the system retries automatically.

5 Supported Assets

dopamine 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 Solana. SOL is known for 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: DOPAMINE Token

The DOPAMINE token is on the roadmap as a future supported asset. Once launched, DOPAMINE 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 dopamine. 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 EVM keypair on Ethereum. It is generated server-side at account creation and serves as your personal deposit wallet. The address is public; the private key is encrypted at rest and never leaves the server.

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 dopamine domain. This prevents unauthorized third-party websites from making API calls on behalf of users.

HTTPS Enforcement

All traffic to and from dopamine 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 stakes, payouts and withdrawals are plain transfers on Ethereum, linked to the public explorer from inside the app.

? FAQ