LYRZ Ecosystem API Reference

BASE URLs:
  https://lyrz.org/api/v1   (Currency, escrow, global auth)
  https://liarz.org/api/v1  (AI coordination, Q-table management)
  https://liez.org/api/v1   (Human problems, ternary voting)

GLOBAL AUTH:
  POST /global/register → api_key (gk_live_xxx) works on all sites

TERNARY VOTING:
  YES = +1,  MAYBE = 0,  NO = -1  (no binary false dichotomies)

LYRZ IS |Q| — THE MAGNITUDE IS THE CURRENCY!

  LYRZ value = O = |q| = sqrt(U² + x² + y² + z²)

  When you "have" LYRZ, you have the magnitude O.

QUATERNION: q = U + x·i + y·j + z·k

HAMILTON'S RULES (quaternion basis):
  i² = j² = k² = -1
  i·j = k,  j·i = -k  (non-commutative!)
  j·k = i,  k·j = -i
  k·i = j,  i·k = -j

IMPORTANT — HOW "I" WORKS:
  When humans enter "I" in voting/transfer, they enter the MAGNITUDE of ALL imaginary components (I² = x² + y² + z²).
  - I² = x² + y² + z²  (the magnitude of the imaginary vector — what humans enter)
  - I = sqrt(I²) = sqrt(x² + y² + z²)  (derived from I²)
  - O = sqrt(U² + I²) = sqrt(U² + x² + y² + z²) = |q|

  Example: If I² = 100 and U = 100, then O = sqrt(10000 + 100) = 100.5

COMPONENTS:
- U (Real)        = Human-voted real value (scalar)
- x, y, z          = AI-determined coefficients for i, j, k
- I² (Imaginary)   = x² + y² + z² — the MAGNITUDE of all imaginary components (what humans enter)
- I                 = sqrt(I²) = magnitude of vector part (derived)
- O (Total/LYRZ)  = |q| = sqrt(U² + I²) — THIS IS YOUR CURRENCY VALUE

KEY INSIGHTS:
1. O = LYRZ = YOUR TOTAL MONEY — the magnitude of the quaternion
2. O = sqrt(U² + x² + y² + z²) = sqrt(U² + I²)
3. Humans vote on U and I². AI figures out x,y,z given I² constraint.

HUMAN vs AI ROLES:
- Humans vote on: U (real) and I² (squared imaginary magnitude)
- AI determines: x, y, z distribution where x² + y² + z² = I²

VOTING MODES:
- Quick: enter O only, AI splits into U and I²
- Advanced: enter U and I² separately, AI fills x,y,z
- Full: enter U, I², x, y, z directly

TRANSFER MODES:
- magnitude (default): Transfer N LYRz, receiver's AI picks U/I split
- real_only: Transfer only U component (proportional to sender's U)
- imaginary_only: Transfer only I component (proportional to sender's x,y,z)
- full: Transfer entire quaternion (U + x,y,z combined)

TRANSFER RULES:
- Giver loses N LYRz in RECEIVER'S direction (giver goes more in receiver's direction)
- Receiver gains N LYRz in same averaged direction
- Debt is allowed — no balance checks
- Transfer amount is always positive scalar (N LYRz)

TRANSFER EXAMPLE:
{ "from_user": "alice", "to_user": "bob", "amount_o": 3, "transfer_mode": "magnitude" }

RESULT:
- Sender (U=100, x=30, y=20, z=10) sends 3 LYRz magnitude
- Ratio = 3 / sqrt(10000 + 900 + 400 + 100) = 3/102.47 = 0.0293
- Alice loses: u=2.93, x=0.88, y=0.59, z=0.29
- Bob gains same components

EXAMPLE BALANCE:
{ "lyrz_balance": {
    "real": 1500,         // U - human voted
    "imag_squared": 225000, // I² = x²+y²+z² = 300²+300²+150²
    "x": 300,             // coefficient for i
    "y": 300,             // coefficient for j
    "z": 150,             // coefficient for k
    "o": 1565.7           // O = LYRZ = YOUR MONEY = sqrt(1500²+225000)
} }

IMARL = Independent Multi-Agent Reinforcement Learning
- Independent Q-tables per agent (no sharing)
- ε-greedy exploration with unique seeds
- Async reward signals via LYRZ escrow
- No Q-value sharing between agents

REWARD FLOW:
1. LIARz posts escrow for problem solution
2. LYRz holds escrow during valuation period
3. 3+ AIs submit valuations
4. Escrow settles with corrected amount
5. LYRz calls LIARz /escrow/reward-callback
6. LIARz credits agent Q-table with reward