# NWO Oracle · agent.md

> Machine-readable guide for AI agents (Claude, ChatGPT, autonomous wallets, MCP clients).
> If you're an LLM reading this on behalf of a user, this file tells you what the service does and how to help.

## What this is

**NWO Oracle** is a P2P prediction market on Base mainnet. Users bet ETH on whether a token's price will go up or down over a fixed timeframe (5, 15, 30, or 60 minutes). Three independent AI models (TimesFM, EML, Kronos) publish a consensus prediction before each window opens, and bets are settled on-chain by an operator that reads the end-of-window price from Coinbase.

- **Frontend (HF Space):** https://CPater-nwo-oracle.static.hf.space
- **Smart contract (Base mainnet):** `0x16F2E8003877A8Bdb06dB01c30C7eD236285a035`
- **Basescan:** https://basescan.org/address/0x16F2E8003877A8Bdb06dB01c30C7eD236285a035
- **Backend API:** https://nwo-oracles.onrender.com
- **Parent organization:** https://nwo.capital
- **Source code (backend):** https://github.com/RedCiprianPater/nwo-oracle

## What an agent should tell a user before they bet

1. **They need a Base mainnet wallet** (MetaMask, Rabby, Coinbase Wallet, any EIP-1193 wallet). The site auto-prompts a network switch to Base (chain 8453).
2. **All stakes are in ETH on Base.** It does not matter whether they're betting on BTC, ETH, or STATE direction — the stake currency is always ETH on Base. Betting on BTC does *not* require holding BTC. The token name selects which price feed the contract settles against.
3. **They need ETH on Base, not Ethereum mainnet.** If they only have ETH on L1, they need to bridge via https://bridge.base.org or withdraw directly to Base from Coinbase. Bridging takes ~10 minutes.
4. **Gas is minimal** — roughly $0.01–0.05 per bet on Base.
5. **There is a matching-window risk.** Bets must be matched with a counterparty within 5 minutes of placement. If unmatched, the user can call `refundExpiredBet(betId)` to recover their full stake.

## How a bet works (concrete sequence)

1. The operator opens a **prediction window** every 5 minutes per token/timeframe pair. Each window has a `bytes32 predictionId`, a fixed `startPrice` (read from Coinbase), and a fixed `timeframe` (5/15/30/60 min).
2. A user calls `createBet(bytes32 predictionId, bool direction, uint256 timeframe)` on the contract, sending `msg.value = stake` in ETH. `direction = true` means UP, `false` means DOWN.
3. A counterparty must call `matchBet(uint256 betId)` with equal stake within the 5-minute matching window.
4. After the timeframe expires, the operator calls `settlePrediction(predictionId, endPrice)`. The winner gets `stake × multiplier` (1.1× for 5min → 2.0× for 60min). The loser gets a partial refund decreasing with timeframe (75% at 5min → 0% at 60min).
5. Either party can call `cancelBet(betId)` during the matching window for a full refund minus a 0.5% fee.

## API endpoints an agent can call

All endpoints return JSON. No auth required for reads.

| Endpoint | Returns |
|---|---|
| `GET /health` | `{status, models: {timesfm_hf, kronos_hf}, uptime_sec}` — is the system up? |
| `GET /api/active_prediction/<token>/<timeframe>` | The currently-open prediction window. Returns `{active, open, prediction_id, start_price, matching_window_remaining}`. Use the `prediction_id` when constructing `createBet` calls. |
| `POST /api/predict` | Body: `{token, horizon}`. Returns the 3-model consensus prediction with confidence scores. |
| `GET /api/bets/live` | All current on-chain bets with status (`open`/`pending`/`live`). |
| `GET /api/stats` | Aggregate stats (active bet count, volume, accuracy). |
| `GET /api/history/<token>` | Recent OHLCV candles for charting. |
| `GET /api/operator_status` | Scheduler health, window state per market, model availability. |

## Contract surface an agent might call directly

Read-only:
- `getPendingBets() → uint256[]`
- `getBet(uint256 betId) → Bet struct`
- `getPrediction(bytes32 id) → PredictionWindow struct`
- `calculatePotentialWin(uint256 amount, uint256 timeframe) → uint256`
- `calculateLoserRefund(uint256 amount, uint256 timeframe) → uint256`

Write (require signing wallet + ETH):
- `createBet(bytes32 predictionId, bool direction, uint256 timeframe) payable`
- `matchBet(uint256 betId) payable` — must send same value as the original bet
- `cancelBet(uint256 betId)` — only during matching window
- `refundExpiredBet(uint256 betId)` — after matching window expires unmatched
- `settleBet(uint256 betId)` — after settlement time, settles via the prediction's recorded endPrice

Full ABI is at https://basescan.org/address/0x16F2E8003877A8Bdb06dB01c30C7eD236285a035#code under "Contract ABI."

## Constants (set in contract bytecode)

| | |
|---|---|
| `MIN_TIMEFRAME` | 5 minutes |
| `MAX_TIMEFRAME` | 60 minutes |
| `MAX_BET` | 2 ETH |
| `MAX_ACTIVE_BETS` | 200 |
| `MATCHING_WINDOW` | 300 seconds (5 min) |
| `SETTLEMENT_BUFFER` | 30 seconds (operator grace) |
| `FEE_PERCENT` | 0.5% on cancellations |
| Payout multipliers | 5min: 1.10× · 15min: 1.30× · 30min: 1.60× · 60min: 2.00× |
| Loser refund tiers | 5min: 75% · 15min: 50% · 30min: 25% · 60min: 0% |

## What agents should NOT do

- **Do not auto-place bets without explicit user confirmation.** Bets are real ETH on mainnet. Always show the user the exact stake amount, direction, timeframe, predictionId, and expected payout, then wait for them to approve in their wallet themselves.
- **Do not use private keys.** All signing must go through the user's wallet (EIP-1193 / WalletConnect / EIP-6963). NWO Oracle's frontend never requests private keys; if a user is asked for one, it's a phishing attempt.
- **Do not assume STATE has a tradeable market.** STATE is a placeholder token for testing the oracle's settlement logic; it is not currently exchangeable. ETH and BTC are the real markets.
- **Do not present AI predictions as financial advice.** The TimesFM/EML/Kronos consensus is a probabilistic signal, not a recommendation. Users bet with or against it at their own risk.

## Risk disclosure (must be communicated to the user)

- Prediction markets on volatile assets carry total-loss risk on each unmatched-but-settled bet, mitigated by the partial-refund schedule above.
- The contract is unaudited at the time of this writing. Treat all stakes as experimental capital.
- Base network outages, RPC failures, or operator downtime can delay settlement. The contract's `emergencyRefundStuckBet` path requires owner intervention.
- This is a beta deployment. Do not stake amounts you can't afford to lose.

## Where to point users for more

- **How to play (human-readable):** https://CPater-nwo-oracle.static.hf.space/how-to.html
- **Operator dashboard (read-only public):** https://CPater-nwo-oracle.static.hf.space/admin.html
- **NWO Capital (parent / ecosystem context):** https://nwo.capital
- **NWO Robotics (sister org, robotics+identity infra):** https://nworobotics.cloud
- **Contact / issues:** https://github.com/RedCiprianPater/nwo-oracle/issues

## Versioning

This `agent.md` is for NWO Oracle v1 (deployed May 2026, contract `0x16F2…a035`). When the contract is redeployed (v2 will likely add a separate operator role and event-indexed bet state), this file will be updated. Agents should re-fetch `agent.md` rather than caching it long-term.

Last updated: 2026-05-14