Poll SDK

Core Concepts

Understand the fundamental concepts of the Poll SDK and betting protocol.

Bet Lifecycle

SetupBettingResolutionSettlement
create-bet.tsView full guide →
const txHash = await sdk.initializeBetV2({
  question: "Will BTC hit $100k by March?",
  expectedUserCount: 2,
  minimumVoteCount: 2,
  isCreatorResolver: false,
  signers: [wallet],
});

Overview

The Poll SDK enables you to build applications on top of the Poll.fun betting protocol on Solana. This guide covers the key concepts you need to understand.

Program User

Every user interacting with the protocol needs an onchain Program User account. This account:

  • Tracks the user's betting statistics
  • Maintains wager counts and amounts
  • Links to the user's wallet address
typescript
const userAddress = sdk.addresses.user.get(wallet.publicKey);
const userAccount = await sdk.accounts.user.single(userAddress);

console.log("Total wagers:", userAccount.totalWagersCount);
console.log("Total wagered:", userAccount.totalWageredAmount);

Bet

A Bet is a prediction market with:

  • Question: The topic being bet on
  • Options: Typically "For" (Yes) and "Against" (No)
  • Wagers: User positions with USDC amounts
  • Votes: Resolution votes from participants
  • Status: Draft → Pending → Resolving → Resolved → Distributed
typescript
const betAccount = await sdk.accounts.betV2.single(betAddress);

console.log("Question:", betAccount.question);
console.log("Status:", betAccount.status);
console.log("Total For:", betAccount.totalOiFor);
console.log("Total Against:", betAccount.totalOiAgainst);

Wager

A Wager represents a user's position on a bet:

  • Amount: USDC locked in escrow
  • Side: For (Yes) or Against (No)
  • Status: Open → SettledWin or SettledLoss

The pool of all wagers determines the payout ratios. Winners split the total pot proportionally based on their wager amounts.

Voting & Resolution

Bets are resolved through consensus voting:

1. Any participant can initiate voting 2. All participants (or designated resolvers) cast votes 3. When minimumVoteCount is reached with consensus, the outcome is determined 4. Settlement distributes winnings minus protocol fees

typescript
import { Outcome } from "@solworks/poll-sdk";

// Outcome options
Outcome.NotResolvedYet; // 0 - Default state
Outcome.For;            // 1 - "Yes" wins
Outcome.Against;        // 2 - "No" wins
Outcome.Tied;           // 3 - Push, refunds issued

Market Status

Bets progress through defined states:

StatusDescription
DraftInitial state, not yet active
PendingActive, accepting wagers
ResolvingVoting in progress
ResolvedOutcome determined, awaiting settlement
DistributedPayouts complete
CanceledBet canceled, refunds issued
RefundedAll wagers returned
typescript
import { MarketStatus } from "@solworks/poll-sdk";

if (betAccount.status === MarketStatus.Pending) {
  console.log("Bet is accepting wagers");
}

Program Derived Addresses (PDAs)

The SDK provides helpers to derive onchain account addresses:

typescript
// Protocol config
const protocolAddress = sdk.addresses.protocol.get();

// User account
const userAddress = sdk.addresses.user.get(wallet.publicKey);

// Bet account
const betAddress = sdk.addresses.betV2.get(wagerId, creator);

// Pool (escrow) address
const poolAddress = sdk.addresses.poolAuthority.get(wagerId, creator);

USDC & Token Accounts

The protocol uses USDC (SPL Token) for all wagers:

typescript
// Get token account for a user
const tokenAccount = sdk.addresses.tokenAccount.get(
  usdcMint,
  wallet.publicKey,
  false // allowOwnerOffCurve
);

Next Steps

Now that you understand the core concepts, follow the step-by-step guides to implement each part of the betting flow.

PreviousQuick StartNextCreate a Wallet