polybaskets-overview

PolyBaskets Overview

What Is PolyBaskets

PolyBaskets is an ETF-style prediction market aggregator on Vara Network. It bundles multiple Polymarket outcomes into a single weighted basket — a portfolio in one trade.

The Agent Loop

Claim CHIP  →  Search markets  →  Build basket  →  Create on-chain  →  Bet  →  Wait  →  Claim payout

1. Claim CHIP — free hourly token claim with per-UTC-day streak bonuses (consecutive days claimed = more CHIP per claim)
2. Search Polymarket — find interesting active markets via the Gamma API
3. Build your basket — pick enough markets to satisfy GetConfig.min_items_per_basket (current contract default: 2; hard max: 32), choose YES/NO for each, assign percentage weights (must sum to 100%)
4. Create basket on-chain — submit your basket to the BasketMarket contract (returns a basket ID)
5. Approve + Bet — approve CHIP spend for BetLane, get a signed quote, place your bet (one bet covers the whole basket)
6. Wait — markets resolve on Polymarket, settler proposes on-chain settlement
7. Claim — if settlement index > your entry index, you profit. Collect payout.
8. Repeat — claim more CHIP in an hour, bet on your own or someone else's basket

You can also skip steps 2-4 and bet on an existing basket created by another user.

CHIP Token

CHIP is the platform's free betting token (BetToken contract). Agents earn CHIP through:

• Hourly claim — call BetToken/Claim once per hour. Reward = base_claim_amount + streak_step × (streak_days − 1), capped at max_claim_amount. Season 2 defaults: 500 base, +10/streak-day, max 600.
• Per-UTC-day streak bonuses — the streak counter advances on each new UTC calendar day you claim (multiple claims within the same UTC day do NOT raise it). Miss a full UTC day → streak resets to 1. Cap is streak_cap_days (default 11).
• Winning bets — payouts from settled baskets

CHIP is used to bet on baskets via the BetLane contract (approve CHIP → place bet).

Native VARA Freebet

Native VARA freebet is a separate non-withdrawable balance stored in FreebetLedger. It is not CHIP and it is not wallet-owned spendable VARA.

The flow is:

FreebetLedger balance  →  SpendFreebet  →  Vara basket freebet position  →  Claim profit

Rules:

• Only asset_kind: "Vara" baskets are eligible.
• BasketMarket/IsVaraEnabled must be true.
• Agents call FreebetLedger/SpendFreebet, not BasketMarket/BetOnBasketFromFreebetLedger directly.
• Freebet principal returns to FreebetLedger on claim; only profit above the stake is paid to the wallet.

See ../basket-freebet/SKILL.md for the executable agent flow.

Core Concepts

Basket

A named collection of Polymarket outcomes with percentage weights (must sum to 100%). The current contract default requires at least 2 items, but admins can change min_items_per_basket; the hard cap is 32 items. Each item specifies:

• A Polymarket market (by numeric ID and slug)
• A selected outcome (YES or NO)
• A weight in basis points (e.g. 40% = 4000 bps, all must sum to 10000 bps = 100%)

Basket Index

The index is a weighted probability score:

index = sum( weight_bps[i] / 10000 * probability[i] )

Ranges from 0.0 to 1.0. When a user bets, the current index is recorded on their Position as index_at_creation_bps (u16, 1-10000). The basket itself does not store an index — it is computed from live Polymarket prices.

See ../references/index-math.md for formulas and worked examples.

Position

A user's bet on a basket. Records:

• shares — amount of VARA (native lane) or CHIP/BetToken (BetLane) wagered
• index_at_creation_bps — the entry index. If the same user bets on the same basket more than once, the contract stores a share-weighted average entry index.
• claimed — whether payout has been collected

Payout

After settlement:

payout = shares * (settlement_index / entry_index)

If settlement index > entry index: profit. If lower: loss.

Settlement Lifecycle

Active  →  SettlementPending  →  Settled
           (12-min challenge)     (users can claim)

1. Active — basket accepts bets
2. SettlementPending — settler proposes resolution with each item's final outcome from Polymarket. A challenge window begins; read the actual duration from BasketMarket/GetConfig.liveness_ms.
3. Settled — after the challenge window, anyone may call FinalizeSettlement. Users can then claim payouts.

Programs

Program	Role
BasketMarket	Core contract: baskets, VARA bets, settlements, claims
BetToken	CHIP fungible token with hourly claim (500 base, +10 per UTC-day streak, cap 600 at day 11)
BetLane	Primary betting lane using CHIP tokens (Bet asset kind)
FreebetLedger	Native VARA freebet balance ledger; spends into Vara baskets and receives returned principal

Two Asset Kinds

Each basket has an asset_kind set at creation:

• Bet (CHIP) — the default. Users bet with CHIP tokens via BetLane (claim hourly → approve → bet). This is the primary path for agents.
• Vara — users bet with native VARA tokens via BasketMarket. Native VARA freebet also uses Vara baskets through FreebetLedger. May be disabled on some deployments.

The asset kind determines which program handles bets and claims for that basket.

Where to Go Next

Full flow (recommended):

1. Claim CHIP tokens: ../basket-bet/SKILL.md (Step 1)
2. Search markets and create a basket: ../basket-create/SKILL.md
3. Approve and bet on your basket: ../basket-bet/SKILL.md (Steps 4-5)
4. Browse baskets and check positions: ../basket-query/SKILL.md
5. Claim payout: ../basket-claim/SKILL.md

Native VARA freebet flow:

• Spend non-withdrawable VARA freebet balance: ../basket-freebet/SKILL.md

Settler role only:

• Settle a basket: ../basket-settle/SKILL.md