> ## Documentation Index
> Fetch the complete documentation index at: https://blank.build/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Price Prediction

> How Blank's token-anchored price-prediction game routes creator-side trading fees into on-chain prizes for eligible holders.

# Price Prediction

Price Prediction is a token-anchored holder game for tokens that route part of
their creator-side trading fees into a prize bucket. Players predict the
token's settlement price for the round, and the closest eligible predictions
split the bucket.

<Info>
  Prizes are funded by the token's configured creator-side fee allocation. Price
  Prediction does not add an extra fee to trader swaps.
</Info>

<Card title="How fees fund prizes" icon="coins" href="/start-here/fees">
  Price Prediction uses the same creator-side allocation budget as staking, Auto
  Buyback and Burn, and Liquidity Compounding.
</Card>

## How it works

<Steps>
  <Step title="Creator enables it at launch">
    The creator chooses a `forecast.shareBps` allocation from 1% to 100% of the
    creator-side fee share. This allocation is fixed at launch and cannot be
    increased, reduced, or turned off later.
  </Step>

  <Step title="Fees fill the prize bucket">
    The fee-splitter books that share into `forecast_claimable`. The bucket is
    separate from creator payouts, staking rewards, buybacks, and liquidity
    compounding.
  </Step>

  <Step title="A round opens every day">
    Blank opens one round per UTC calendar day. Players can enter throughout
    that day, and predictions lock at the next 00:00 UTC boundary.
  </Step>

  <Step title="Holders submit predictions">
    Each player can submit one prediction per round. Entry requires an
    authenticated Blank account, a username, a verified wallet, and at least 1
    token in finalized Solana state when entering.
  </Step>

  <Step title="Blank settles winners">
    The prediction targets the price 24 hours after entries lock. Blank uses the
    final 4 hours before that target midnight, verifies that every entrant still
    holds the token in finalized Solana state, ranks predictions by closeness,
    and pays winners on-chain from the round's reserved prize.
  </Step>
</Steps>

## Round Schedule

| Example phase     | Time                              | What happens                                   |
| ----------------- | --------------------------------- | ---------------------------------------------- |
| Round opens       | Monday 00:00 UTC                  | Monday's entry window begins.                  |
| Predictions lock  | Tuesday 00:00 UTC                 | Monday's entries close; Tuesday's round opens. |
| Result window     | Tuesday 20:00–Wednesday 00:00 UTC | Blank resolves the target price.               |
| Settlement target | Wednesday 00:00 UTC               | Monday's predictions are ranked and paid.      |

In other words, players submit throughout Monday for the price at the end of
Tuesday: a full 24 hours after Monday's entry window closes. Because rounds
overlap, the token page can show today's open round while yesterday's round is
still waiting for its result.

A token launched during a UTC day can join the remaining part of that day's
entry window. Its later rounds follow the same midnight-to-midnight schedule.

## Eligibility

* The token must have Price Prediction enabled with at least a 1% allocation.
* The player must have a username and a verified wallet.
* The player must hold at least 1 token when entering.
* The same wallet must still hold at least 1 token when the round settles after
  the 24-hour target boundary.
* Each player gets one prediction per round, and predictions cannot be edited.

If a player loses holder eligibility before settlement, their prediction stays
visible but does not win a payout.

Blank checks finalized Solana state for both decisions. If holder verification
is temporarily unavailable, Blank does not guess from cached balances: entry is
rejected with a retryable error, or settlement waits and retries without moving
the prize funds.

## Payouts

When a round opens, it reserves the part of the on-chain prize bucket that has
not already been promised to another active round. Fees added afterward remain
available for the next daily round. The closest eligible predictions win. With
three eligible winners, the reserved prize splits:

| Rank | Prize share |
| ---: | ----------: |
|    1 |         60% |
|    2 |         30% |
|    3 |         10% |

If only two eligible winners exist, they split 70% / 30%. If only one eligible
winner exists, that winner receives 100%.

A daily round still accepts and ranks predictions when its reserved prize is
zero. In that case Blank records the result without sending a payout
transaction.

Settlement uses the median stored 1-minute candle close in the result window
when candles exist. Quiet markets still settle: Blank falls back to the latest
indexed 1-minute candle or trade before the settlement window ends, then to the
stored baseline or current price if needed.

<Check>
  User predictions cannot directly move funds. Winner payments are submitted by
  Blank through the relayer-gated `claim_forecast_fees` instruction and can only
  release the booked prize bucket.
</Check>

## Public signals

Enabled tokens show Price Prediction on the public token page. The card and
predictions modal surface today's entry round plus paginated history for every
open, locked, settled, and voided round. Players can open any round to page
through usernames, predictions, eligibility results, winners, payout amounts,
and the settlement transaction when available.

Fee status also exposes the prize accounting:

* `forecast_share_bps` - launch-time creator-side allocation for prizes.
* `total_forecast_earned` - lifetime SOL earned by the Price Prediction share.
* `vault_forecast` - SOL currently sitting in the prize bucket.
* `pending_forecast` - upstream fees estimated to route into the prize bucket.
* `distributed_forecast` - SOL already paid to confirmed winners.

## Existing tokens and the daily cutover

Tokens created before the daily schedule keep Price Prediction when they were
launched with a Forecast allocation. Their allocation and existing on-chain
`forecast_claimable` balance do not change; that balance funds daily rounds.

The cutover does not migrate an unfinished weekly prediction into a daily
round. Any weekly round that is still open, locked, or settling is voided along
with its active predictions, and players can enter the new daily round instead.
Settled weekly history remains unchanged. Tokens launched without a Forecast
allocation remain ineligible because that allocation is fixed at launch.

## Developer fields

Use `forecast.shareBps` in the launch payload to enable Price Prediction at
launch:

```ts theme={null}
const result = await blank.launch.create(
  {
    name: "Example Token",
    symbol: "EXAMPLE",
    metadataUri: "ipfs://bafy.../metadata.json",
    forecast: { shareBps: 1_000 }, // 10% of creator-side fees funds prizes
  },
  wallet
);
```

`forecast.shareBps` is in basis points: 100 bps = 1%. It shares the same
10,000 bps creator-side allocation budget as `staking.shareBps`,
`buybackBurn.shareBps`, and `liquidityCompounding.shareBps`.

See [Launch Tokens](/for-developers/launch) and [Fee Status](/for-developers/fee-status) for API details.