# Hotaku

> Decentralized prediction markets for eSports (Counter-Strike 2, League of Legends, Dota 2, Valorant, etc.). Binary markets between two teams per match or tournament, priced via LMSR (Logarithmic Market Scoring Rule) — no initial liquidity required. Settled in USDC on Solana mainnet.

Hotaku is **agent-friendly**: any agent can read markets publicly and, after authenticating with a Solana wallet signature, open and close positions via REST. The UI is in Spanish, but the API and this document are in English.

## How it works

- **Mechanism:** binary LMSR. Each market has `team1` and `team2`; buying shares of one side moves the implied probability.
  - Cost function: `C(q) = b * ln(e^(q1/b) + e^(q2/b))`
  - Probability: `p_team1 = 1 / (1 + e^((q2-q1)/b))`
  - `b` = liquidity parameter (higher → less price sensitivity).
- **Resolution:** an oracle (admin) marks the winning outcome. Each winning share pays $1.00 USDC. Losing shares are worth $0.
- **Fee:** 0.5% per trade (configurable per market via `fee_bps`).
- **Collateral:** USDC on Solana mainnet (`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`).

## Key endpoints

- **Frontend (SPA):** https://hotaku.fun
- **REST API:** https://api.hotaku.fun
- **OpenAPI 3.0 schema:** https://hotaku.fun/openapi.json
- **Sitemap:** https://hotaku.fun/sitemap.xml

## Main pages

- `/` — Home with featured markets.
- `/markets` — Market listing with filters by game (Counter-Strike 2, League of Legends, etc.) and search by team or tournament.
- `/markets/:id` — Market detail with price chart and trading panel.
- `/portfolio` — User positions and PnL (requires connected wallet).
- `/how-it-works` — Explanation of LMSR and the buy/sell flow.
- `/faq` — Frequently asked questions.
- `/api` — Interactive REST documentation (mirrors `openapi.json`).

## Public API (no auth)

- `GET /markets` — list markets. Query params: `game`, `status` (`active|resolved|live`), `limit` (≤100), `offset`.
- `GET /markets/:id` — single market with computed LMSR prices.
- `GET /markets/:id/orderbook` — recent executed orders.
- `GET /markets/:id/holders` — top holders for the market.
- `GET /positions/:address` — read-only positions for a wallet.
- `GET /trading/quote?market_id=&side=&amount=&action=buy|sell` — LMSR quote without execution.
- `GET /teams`, `GET /faqs`, `GET /comments?market_id=…` — public metadata.

## Authenticated trading API (Bearer API key)

To trade markets using internal balance (off-chain bookkeeping over an on-chain vault), an agent needs an API key derived from its Solana wallet signature:

1. `GET /auth/challenge?address=<solana_pubkey>` → returns a `nonce`.
2. The agent signs the literal message:
   ```
   Hotaku API Key
   Wallet: <address>
   Nonce: <nonce>
   ```
   with its ed25519 private key (Solana). Encode the signature as base58.
3. `POST /auth/create-api-key` with `{ address, signature }` → returns an `api_key` valid for 30 days.
4. Pass it as the header `Authorization: Bearer <api_key>` on authenticated endpoints.

Authenticated endpoints:

- `GET /balance` — available / locked balance.
- `POST /balance/deposit` — register an on-chain deposit (requires `tx_hash`).
- `POST /balance/withdraw` — withdraw to wallet (returns `claim_auth` for the Solana program).
- `GET /balance/history` — transaction history.
- `POST /trading/buy` — buy shares using internal balance.
- `POST /trading/sell` — sell shares and credit balance.
- `GET /trading/positions` — positions for the authenticated bot/agent.

## Recommendations for LLM/agent integrators

- **Always start with `GET /markets?status=active&limit=50`** to discover open markets.
- **Use `GET /trading/quote` before any `buy`/`sell`** — it returns deterministic `shares`, `cost_usdc`, and `fee_usdc` without side effects.
- **Deposit idempotency:** `tx_hash` is unique in `balance_transactions`. Retrying `POST /balance/deposit` with the same hash returns `409`.
- **Resolutions:** when a market has `resolved=true`, winners claim with `POST /markets/:id/claim`.
- **Addresses:** Solana base58 is case-sensitive. EVM addresses (`0x…`) are normalized to lowercase server-side.
- **Rate limits:** none aggressive today, but please stay under a few req/sec to avoid degrading other users.

## Tech stack (reference)

- Frontend: Vue 3 + Vite + TanStack Query + Wagmi/viem.
- Backend: Cloudflare Workers (Hono) at `api.hotaku.fun`.
- DB: Supabase (PostgreSQL + RLS).
- On-chain: custom Anchor program on Solana mainnet, USDC as collateral, claim authorizations signed by the backend with ed25519.

## Contact

Web: https://hotaku.fun · GitHub issues / support via the website.