Basket Documentation
Build AI-constructed, risk-smoothed prediction market baskets on DreamDEX.
What is Basket?
Basket transforms single directional views into diversified positions across multiple time windows. Instead of making one all-or-nothing bet, spread your thesis across correlated DreamDEX Event Contracts with AI-powered construction and transparent reasoning.
Key Features
- AI Construction — Markets selected based on liquidity, volatility, and correlation analysis
- Risk Smoothing — Variance reduction of up to 38% vs single-position bets
- Full Transparency — Every decision explained with data-backed reasoning
- On-Chain Settlement — Permissionless resolution via DreamDEX contracts
- Cross-Asset Support — Combine BTC and ETH markets in single baskets
Getting Started
To start using Basket, you need a Web3 wallet connected to the Somnia Shannon testnet.
1. Connect Wallet
Click "Launch App" and connect using RainbowKit. Supported wallets include MetaMask, Coinbase Wallet, and WalletConnect.
2. Switch to Somnia Shannon
The app will prompt you to switch networks if needed. Somnia Shannon testnet details:
| Network Name | Somnia Shannon Testnet |
| Chain ID | 50312 |
| Currency | STT (testnet) |
| Collateral | tUSDC at 0x70a86D8842FB63C4Ad2b7cdddF530eBf1BB25d8E |
3. Create Your First Basket
Select an asset (BTC/ETH), number of windows (2-5), max spend, and risk tolerance. The AI will construct a proposal with full reasoning for your review.
Architecture
Basket is a Next.js application integrating with the DreamDEX SDK for on-chain market operations, Firebase Firestore for basket tracking, and Google Gemini for AI reasoning.
Tech Stack
- Frontend — Next.js 16, React 19, Tailwind CSS
- Blockchain — Somnia Shannon testnet, DreamDEX Event Contracts
- Wallet — Wagmi + RainbowKit
- Database — Firebase Firestore (UI cache only)
- AI — Google Gemini for market analysis and reasoning
Security Model
Firestore as Cache Only
Firestore is a UI cache synced FROM on-chain reads — never the reverse. All writes happen only after server has verified on-chain status via getMarketOnchain(). The client NEVER writes basket/leg status directly.
DreamDEX SDK
Basket uses @somnia-chain/markets-sdk for all on-chain operations.
Installation
npm install @somnia-chain/markets-sdk
Basic Usage
import { SomniaMarkets, SOMNIA_TESTNET_ADDRESSES } from "@somnia-chain/markets-sdk";
import { somniaShannon } from "@somnia-chain/markets-sdk/chains";
const exchange = new SomniaMarkets({
indexerUrl: "https://dev.smk.somnia.host/v1/graphql",
chain: somniaShannon,
addresses: SOMNIA_TESTNET_ADDRESSES,
});
// Load all markets
await exchange.loadMarkets();
// Get trading markets
const tradingMarkets = Object.values(exchange.markets)
.filter(m => m.type === "binary" && m.active);
// Place an order (requires signer)
exchange.setSigner({ walletClient });
const order = await exchange.createOrder(symbol, "buy", quantity, price);API Reference
Basket exposes several API endpoints for basket construction and management.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/basket/construct | AI constructs a basket proposal |
| POST | /api/basket/approve | Save basket after orders placed |
| GET | /api/basket/list | List user's baskets |
| POST | /api/basket/narrate | Get AI narration of basket status |
| POST | /api/basket/redeem | Get/record redeemable positions |
| GET | /api/markets | List available trading markets |
Smart Contracts
DreamDEX Event Contracts are binary prediction markets where outcomes resolve to 0 or 1.
Contract Addresses (Somnia Shannon)
| tUSDC (Collateral) | 0x70a86D8842FB63C4Ad2b7cdddF530eBf1BB25d8E |
| Exchange Router | SOMNIA_TESTNET_ADDRESSES.router |
Market Lifecycle
- 0 - Listed — Market created but not yet trading
- 1 - Trading — Active, orders can be placed
- 2 - Locked — Trading halted, awaiting resolution
- 3 - Settling — Resolution in progress
- 4 - Resolved — Outcome determined, redemption available
- 5 - Voided — Market cancelled, collateral returned