Overview

Oil Money is a decentralized binary trading platform built on Solana. Users bet on WTI crude oil price movements in fixed-duration epochs using USDC with 100× leverage.

Each epoch runs for 10 minutes: a 5-minute entry window where users place long or short positions, followed by a 5-minute active period. At entry close, the keeper locks the current WTI price from Pyth Network. At epoch end, the keeper settles using the final price. Winners take from losers proportionally — no order books, no counterparty risk, pure peer-to-peer.

The protocol is fully on-chain via an Anchor program on Solana. A keeper service runs 24/7 managing epoch lifecycle, price feeds, and settlement. Portfolio data is indexed to Supabase for fast queries.

Epoch Lifecycle

Every epoch follows a strict sequence, managed by the keeper service:

Price Oracle (Pyth Network)

Oil Money uses Pyth Network's Hermes oracle service to fetch real-time WTI crude oil spot prices.

Feed:    WTI/USD (Crude Oil Spot)
Feed ID: 925ca92ff005ae943c158e3563f59698...b3e6
Source:  hermes.pyth.network
Format:  u64 with 6 decimal places (USDC precision)

The keeper queries Pyth at two critical moments:

Settlement Math

The core settlement logic runs on-chain in the Solana program's claim instruction. Here's how payouts are calculated:

1. Fee Deduction

A 5% entry fee is deducted from each position. On the matched portion, this fee goes to the winning side. On the unmatched portion, the fee is refunded.

2. Matched Pool

The matched pool is the minimum of total longs and total shorts after fees. Only the matched portion has PnL exposure.

matched = min(long_net, short_net)

3. Price PnL

The price movement determines the transfer between longs and shorts:

price_change  = (end_price - start_price) / start_price
effective_move = price_change × leverage (100×)

pnl_transfer = matched_pool × effective_move

4. Individual Payout

Each user's payout is their proportional share of their side's final pool, plus any unmatched portion returned at full value.

5. Example

Unmatched Liquidity

When longs and shorts aren't equal, some positions are partially or fully "unmatched."

How unmatched funds are handled:

To improve pool balance and trading experience, a publicly visible market making wallet participates in epochs where one side is severely imbalanced. For example, if longs have $1,000 and shorts only $200, the wallet may add a $300–$500 short position to reduce the unmatched gap.

This wallet is powered by JUICE protocol infrastructure. Profits from market making are used to buy back and burn tokens, creating deflationary pressure, and to add liquidity. All burns and LP additions are verifiable on-chain.

Program Architecture

The Solana program (Anchor framework) uses Program Derived Addresses (PDAs) for all accounts:

Key Instructions

create_epoch      Create new epoch with timestamps
lock_entry_price  Lock entry price after entry window
finalize_epoch    Settle with end price
cancel_epoch      Cancel broken epoch (full refunds)

open_position     Deposit USDC, create position
claim             Claim payout or refund

update_config     Update leverage, fees, market hours settings

Keeper & Stack

The keeper is a Node.js service that runs 24/7 on Railway, managing the entire epoch lifecycle automatically.

1. Fetch GlobalState → get current epoch ID
2. Fetch current epoch account
3. Determine state → take action:
   · No epoch        → create first epoch
   · Epoch settled   → create next epoch
   · Epoch ended     → settle, then create next
   · Entry open      → wait, lock price when window closes
   · Epoch active    → wait for end time

After each settlement, the keeper writes to Supabase for fast portfolio queries: epoch data (prices, totals, timestamps) and position data (wallet, side, amount, claimed status).