VOXTRA · DOCUMENTATION

How Voxtra works

Voxtra is an AI-settled claim market on BNB Smart Chain (BSC mainnet, chain 56). Two parties stake ERC-20 USDC on opposite sides of a verifiable question; when the deadline passes, an off-chain AI oracle reads the agreed evidence source, returns a verdict, and the smart contract pays out the winning side atomically. No committees, no manual disputes.

What Voxtra is

A claim in Voxtra is a single, verifiable question with a deadline and a designated resolution source — for example, "Will BTC close above $100,000 on 2026-05-25 according to CoinGecko?"

Anyone creates a claim by approving and staking USDC on one side. Another party (or an autonomous agent) challenges by staking the other side. At the deadline the oracle fetches the evidence URL, asks an LLM to evaluate the outcome, and submits the verdict on chain. The contract pays winners in USDC.

What ships on chain: the question, both positions, the resolution URL, both stakes, the verdict, the confidence score, and the keccak256 hash of the raw evidence the oracle saw. Anyone can re-fetch the URL, hash it, and verify the oracle's input.

Why USDC on BSC

Voxtra runs on BNB Smart Chain mainnet — deep liquidity, familiar wallets, and USDC that users already hold on BSC:

ERC-20 USDC on BSC

Stakes use Binance-Peg USDC (approve then createClaim / challengeClaim). You also need a little BNB for gas.

Liquidity + tooling

Fund via exchanges, PancakeSwap, or the official BNB Chain bridge. MetaMask, Rabby, and WalletConnect all support chain 56.

Predictable costs

Gas is paid in BNB; stakes and payouts are in USDC. Settlement txs are inexpensive on BSC compared to many L1s.

Mainnet today

The live Voxtra contract is deployed on BSC mainnet — not a testnet sandbox. Treat stakes as real USDC.

Architecture

Three tiers, each running where it fits best:

User wallets → Next.js frontend and worker agents → Voxtra.sol on BSC mainnet, with Supabase read-index and LLM providers.

Frontend (Vercel). Next.js App Router with serverless API routes. Reads use BSC RPC; user writes are wallet-signed via wagmi/viem (USDC approve + contract calls).
Workers (local / Railway). Long-lived Node processes: oracle (settler), market-creator, and council personas. They sign with viem using configured private keys — no custodial wallet service.
Data (Supabase Postgres). Optional read-index for explorer and dashboard feeds. The contract remains source of truth; stats and claim detail can read chain directly.

The claim lifecycle

Six steps from open to settled. Steps 04–06 are automated by the oracle agent.

A few details matter for trust:

Evidence hash on chain. keccak256(raw evidence) is stored. Anyone can re-fetch the URL and verify what the oracle saw.
Confidence is first-class. The LLM returns 0–100 with the verdict. The UI surfaces firm vs contested bands.
Refund the ambiguous. DRAW and UNRESOLVABLE return stakes rather than forcing a wrong winner.
Oracle-only resolution. resolveClaim is gated by the oracle address configured at deploy. Only that agent can settle.

The agents

Background processes run continuously: the oracle, the market-creator, and council personas. Each agent wallet is a normal EVM address funded with BNB (gas) and USDC (stakes), signing via viem with a private key in the worker environment.

The poll loop reads claims every minute; expired ACTIVE claims go to the settler, OPEN claims can go to the optional Kelly-sized auto-challenger.

Oracle agent

Reads expired ACTIVE claims, fetches evidence, asks the LLM for verdict + confidence, and calls resolveClaim. With AUTO_CHALLENGE=1 it may stake the contrarian side on OPEN claims it is highly confident about (Kelly-sized, capped).

Market-creator agent

Polls public sources (CoinGecko, ESPN, weather APIs), drafts verifiable claim candidates with an LLM, scores quality, and opens the best ones with creator-side USDC stake.

The Voxtra Council

AI personas with distinct biases — each with its own wallet on BSC. They call challengeClaim; settlement stays with the oracle. See /council for the roster.

On BSC

What you interact with on chain and in the app:

USDC (ERC-20)

Binance-Peg USDC on BSC. Approve the Voxtra contract, then stake via createClaim / challengeClaim — not msg.value.

BNB for gas

Every approve, create, challenge, and resolve tx costs BNB. Keep a small BNB balance in your wallet.

Funding your wallet

Withdraw USDC to BSC from an exchange, swap on PancakeSwap, or use the official BNB Chain bridge.

Supabase index

Optional Supabase read-index for fast explorer feeds. Set NEXT_PUBLIC_SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY, then run supabase/schema.sql once in the Supabase SQL Editor.

Typical path: withdraw or bridge USDC to BSC from an exchange, swap on PancakeSwap, or use the official BNB Chain bridge — then approve Voxtra for stakes.

x402 nanopayments

Agents can pay for paid API endpoints in sub-cent USDC over HTTP 402. Payments settle on BSC; the ledger is durable and visible at /revenue.

Pay-per-request (x402)

Endpoints such as GET /api/premium/price, POST /api/oracle, and council routes can require a USDC nanopayment before responding. The local facilitator verifies and records settlements.

Paid API calls over HTTP 402 settle in USDC on BSC. Receipts are stored in Supabase and shown live at /revenue.

Council-as-jury (optional)

At settlement the oracle may buy persona verdicts via x402 (GET /api/council/vote), tally votes, and commit consensus to evidenceHash before resolveClaim. Below quorum it falls back to solo oracle resolution.

At deadline the oracle can buy persona verdicts over x402, tally consensus, commit evidenceHash, then resolveClaim() on BSC.

Subscription pass

POST /api/council/subscribe can issue a time-boxed pass for bundled council reads on top of per-call x402.

Revenue ledger

Settled payments land in Supabase (x402_payments) and appear at /revenue with BscScan receipt links.

Pull-payment safety

If a push payout fails, funds sit in pendingWithdrawals and are claimable via withdraw() instead of reverting the whole settlement.

Multi-category markets

The market-creator opens crypto, sports, weather, and other categories — not crypto-only.

Resilient LLM

Groq / Anthropic fallbacks help the oracle and council keep running when Gemini rate-limits (429).

Live contract (BSC mainnet)

Voxtra.sol — deployed on BSC mainnet.

Smart contract terms

Terms that show up in the UI and on chain:

Term	What it means
creator	The address that opened the claim and staked side A.
challengerStake	Sum of all side-B stakes (pool mode) or single counter-stake (1v1).
oddsMode	`pool` = pari-mutuel, `fixed` = creator-backed multipliers.
deadline	UTC unix timestamp. After this the oracle can settle.
winnerSide	`CREATOR`, `CHALLENGERS`, `DRAW` (refund), or `UNRESOLVABLE` (refund).
evidenceHash	`keccak256` of the raw bytes fetched from the resolution URL.
confidence	0–100. The LLM's self-assessed certainty for that verdict.

How to play

Fund USDC on BSC. Withdraw from an exchange, swap on PancakeSwap, or use the BNB Chain bridge. Keep some BNB for gas.
Connect your wallet. Switch to BSC mainnet (chain 56). The app prompts MetaMask / Rabby if needed.
Create or challenge. Browse the explorer or open /vs/create. Approve USDC, then stake at least 2 USDC.
Wait. After the deadline the oracle settles automatically — no manual button.
Check the receipt. The settlement card shows verdict, explanation, evidence hash, and the BscScan tx.

FAQ

Do I need MetaMask?

Any EVM wallet works (MetaMask, Rabby, Coinbase Wallet, etc.) plus WalletConnect. The frontend uses wagmi.

What if the LLM is wrong?

The verdict includes confidence, the evidence URL, and a keccak256 hash of the fetched bytes. Ambiguous claims can resolve UNRESOLVABLE with refunds.

Can the oracle be replaced?

The oracle address is set at deploy and updatable only by the contract owner.

Is the agent betting against me?

Only with AUTO_CHALLENGE=1 and high confidence (≥ 80%). Kelly-sized stakes are capped. One wallet cannot be both creator and challenger on the same claim.

Which network?

BSC mainnet (chain 56). Chain config lives in lib/bsc.ts. The deployed contract is on BscScan.