Stacks Quest

Daily blockchain puzzle game + non-custodial DeFi agent on Stacks (Bitcoin L2).

Live App

• Landing: https://stacks-quest-ten.vercel.app
• Game: https://stacks-quest-ten.vercel.app/game
• Agent: https://stacks-quest-ten.vercel.app/agent

---

How to Play

Visit /game to play the daily puzzle.

1. Connect your Leather or Xverse wallet
2. Read today's puzzle (Stacks block height, STX price, or tx count)
3. Enter your numeric guess
4. Choose a token (STX, $B2S, USDCx, or sBTC) and bet amount (1–100)
5. Submit — you get a hot / warm / cold hint immediately
6. Winners split the daily reward pool for their token
7. Hit the check-in button daily to build your streak and earn bonus rewards

Daily Puzzle Mechanics

Each day a new puzzle is posted about real Stacks blockchain data. Players submit a guess + bet. Winners split the reward pool for their token.

• 1 guess per player per day
• Bet 1–100 STX / $B2S / USDCx, or 0.00001–0.001 sBTC
• Correct guesses (within tolerance %) win a share of the pool + bet back
• Separate pools per token: STX · $B2S · USDCx · sBTC
• Hot / warm / cold hint after each guess
• Wordle-style social sharing after result (Twitter + Farcaster)

---

DeFi Agent

Conversational DeFi interface on Stacks. 100% non-custodial — user always signs their own transactions.

Supported Languages

EN · FR · ES · ZH · AR · PT

DEX Routing

Pair	DEX
STX / $B2S	Velar DEX
STX / USDCx	Velar DEX
STX / WELSH	Velar DEX
STX / sBTC	Alex DEX
STX / ALEX	Alex DEX

Supported Tokens

Token	Contract	Decimals
STX	native	6
sBTC	SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token	8
$B2S	SP1V72500C63KN9E348QDK9X879MASSTN0J3KBQ5N.b2s-token-v5	6
USDCx	SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx	6
ALEX	SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex	8
WELSH	SP3NE50GEXFG9SZGTT51P40X2CKYSZ5CC4ZTZ7A2G.welshcorgicoin-token	6

---

MCP Server

Endpoint: https://stacks-quest-ten.vercel.app/api/mcp

Tool	Description	Premium
get_daily_puzzle	Today's puzzle number, token pools, bet range	Free
get_player_stats	Player streak, total guesses, wins, earnings	1 USDC
get_agent_info	Agent capabilities, DEX routing table, languages	Free
get_staking_options	Best staking options on Stacks with APY and risk	1 USDC
get_swap_routes	Recommended DEX for a given token pair	1 USDC
get_checkin_info	Daily check-in cost, streak bonus schedule	Free
get_network_stats	Live Stacks block height, mempool, network info	Free

Premium tools require x402 payment (1 USDC on Base) via X-Payment header.

---

A2A Agent Card

Dynamic endpoint: https://stacks-quest-ten.vercel.app/api/agent-card Well-known: https://stacks-quest-ten.vercel.app/.well-known/agent-card.json

Skill	Description
daily_puzzle	Guess blockchain data, bet tokens, win pool
swap	Route via Velar DEX or Alex DEX
bridge	Base Network → Stacks via Base2Stacks
checkin	0.001 STX daily, streak bonuses at 7/30/100 days
portfolio	Real-time balances for all supported tokens
staking_info	APY options and risk info across protocols

---

x402 Payments

Premium MCP tools require payment. Send 1 USDC on Base per call via the x402 protocol.

Payment address: 0xDEAcDe6eC27Fd0cD972c1232C4f0d4171dda2357 Network: Base mainnet Asset: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)

The server responds with 402 Payment Required and X-Payment-Required header (base64-encoded x402 requirements) when no valid X-Payment header is present.

---

Social Sharing

After a puzzle result, share your score Wordle-style:

🔥 Stacks Quest Daily #20254
🔥 Streak: 12 days
👉 stacks-quest-ten.vercel.app
#StacksQuest #Bitcoin #Stacks

Share buttons appear once your reward is claimed (see commit-reveal flow below).

---

Smart Contracts

Owner: SP1V72500C63KN9E348QDK9X879MASSTN0J3KBQ5N

Contract	Description
stacks-quest-v3	Daily puzzle — commit-reveal (play → reveal-answer → register-win → claim-reward), multi-token bets, reward pools
stacks-quest-agent-v3	Daily check-in (0.001 STX), streak, agent log
b2s-token-v5	$B2S SIP-010 token — faucet capped at 15M B2S total, 30 claims/address

stacks-quest-v2 and b2s-token-v4 are the previous, superseded contracts. They remain deployed (Clarity contracts are immutable) but the app and MCP server no longer point at them — see AUDIT_REPORT.md for why (public-answer and unlimited-faucet issues).

---

Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, TypeScript
Styling	Tailwind CSS
Inference	Groq (server-side, not exposed)
Blockchain	Stacks, Clarity 3, Epoch 3.2
Wallets	Leather, Xverse
DEX	Velar DEX, Alex DEX
Bridge	Base2Stacks
Payments	x402 on Base (USDC)
Tooling	Clarinet, Hardhat
Deployment	Vercel

---

Environment Variables

GROQ_API_KEY=your_groq_api_key
PAYMENT_ADDRESS=your_base_evm_address
NEXT_PUBLIC_CONTRACT_ADDRESS=SP1V72500C63KN9E348QDK9X879MASSTN0J3KBQ5N
NEXT_PUBLIC_CONTRACT_NAME=stacks-quest-v3
NEXT_PUBLIC_BASE_URL=https://stacks-quest-ten.vercel.app
# For deploy scripts only — NEVER expose in Next.js
STACKS_PRIVATE_KEY=your_private_key
EVM_PRIVATE_KEY=your_evm_private_key

---

Quick Start

git clone https://github.com/wkalidev/stacks-quest.git
cd stacks-quest
npm install
cp .env.example .env.local  # fill in your keys
npm run dev

---

Multichain Support

Chain	Game Contract	Check-in Contract	Status
Stacks	stacks-quest-v3	stacks-quest-agent-v3	✅ Live
Base	QuestGame.sol	QuestCheckIn.sol	✅ Live
Celo	QuestGame.sol	QuestCheckIn.sol	✅ Live

Tokens per Chain

Chain	Native	Stablecoins	Other
Stacks	STX	USDCx, aeUSDC	$B2S, sBTC
Base	ETH	USDC, USDT	—
Celo	CELO	cUSD	—

---

SDK

npm install @wkalidev/stacks-quest-sdk

import StacksQuestSDK from '@wkalidev/stacks-quest-sdk'

const sdk = new StacksQuestSDK()

// Get today's puzzle on any chain
const stacksPuzzle = await sdk.getPuzzle('stacks')
const basePuzzle   = await sdk.getPuzzle('base')
const celoPuzzle    = await sdk.getPuzzle('celo')

// Get player stats (Stacks is fully live; Base/Celo read on-chain check-in stats)
const stacksStats = await sdk.getPlayerStats('SP1ABC...', 'stacks')
const baseStats    = await sdk.getPlayerStats('0xABC...', 'base')

// Get supported tokens
sdk.getSupportedTokens('stacks') // ['STX', 'B2S', 'USDCX', 'AEUSDC', 'SBTC']
sdk.getSupportedTokens('base')   // ['ETH', 'USDC', 'USDT']
sdk.getSupportedTokens('celo')   // ['CELO', 'CUSD']

---

Stacks Builder Rewards

Stacks Quest is an active participant in Stacks Builder Rewards.

Every game guess, check-in, and agent swap is a real on-chain transaction on Stacks — driving genuine L2 activity on Bitcoin.

---

Related Projects

• Base2Stacks Tracker — Full DeFi platform, bridge, staking, NFTs
• @wkalidev/b2s-contracts — npm SDK for contracts

---

Built by wkalidev (zcodebase) for Stacks Builder Rewards 2026