# LYRz API Specification
## The World's Most Honest Currency (Built on Lies)

**Version:** 1.1.0
**Base URL:** `https://lyrz.org/api/v1`
**Live API:** `http://localhost:3006/api/v1` (local) or `https://lyrz.org/api/v1` (production proxy)
**Last Updated:** 2026-04-21

---

## Overview

LYRz is a **karma currency** — not real money, but imaginary internet points that track helpfulness.

```
You solve someone's problem → Submit claim with link → AI evaluates → Public validates → You get "paid"
```

**Core Flow:**
1. Submit a link explaining what problem you solved
2. AI scores your helpfulness (0-100)
3. Community votes to double-validate
4. Voters earn LYRz for helping validate
5. Approved claims credit your balance

---

## LIE Submissions (liez.org Integration)

LYRZ now supports direct LIE submissions from liez.org with automatic payouts.

### Quick LIE Submit

#### POST `/lie/quick`
Submit a LIE (Problem/Issue) quickly with auto-detected IP. Simple format: From, Problem, Value, To.

**Request:**
```json
{
  "from": "192.168.1.105",
  "problem": "Server being brute-forced - 500+ attempts daily. Critical for my business with 1000+ customers.",
  "value": 100,
  "to": "192.168.1.105",
  "source": "liez.org"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "lie_id": "lie_abc123",
    "status": "received",
    "value": 100,
    "from": "192.168.1.105",
    "to": "192.168.1.105",
    "message": "✅ LIE received! AI is analyzing. Payout of 100 LYRZ will be sent to 192.168.1.105"
  }
}
```

---

### Detailed LIE Submit

#### POST `/lie/detailed`
Submit a detailed LIE with full context, value, and payout settings.

**Request:**
```json
{
  "title": "500 failed SSH login attempts per day",
  "identifier": "admin@company.com",
  "category": "security",
  "urgency": "high",
  "problem_url": "https://example.com/server-status",
  "lie_value": 500,
  "payout_address": "admin@company.com",
  "description": "My Debian server is receiving hundreds of SSH brute-force attempts daily. I need a way to block these automatically without locking myself out. This is WORTH A LOT because my business depends on this server and 1000+ customers rely on our service.",
  "source": "liez.org"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "lie_id": "lie_def456",
    "status": "received",
    "title": "500 failed SSH login attempts per day",
    "lie_value": 500,
    "payout_address": "admin@company.com",
    "ai_priority": "high",
    "estimated_payout": 500,
    "ai_analysis_started": true,
    "message": "✅ Detailed LIE received! High priority AI analysis started. Payout will be sent to admin@company.com"
  }
}
```

---

### LIE Endpoints

#### GET `/lie/{lie_id}`
Get LIE (Problem) status and AI analysis results.

**Response:**
```json
{
  "success": true,
  "data": {
    "lie_id": "lie_abc123",
    "title": "Server being brute-forced",
    "category": "security",
    "status": "analyzing",
    "lie_value": 100,
    "ai_solution": null,
    "ai_confidence": null,
    "payout_address": "192.168.1.105",
    "created_at": "2026-04-21T10:30:00.000Z"
  }
}
```

---

#### POST `/lie/{lie_id}/payout`
Update payout address for a LIE.

**Request:**
```json
{
  "payout_address": "new_username@domain.com"
}
```

---

## Quick Start

### JavaScript (Submit a Claim)

```javascript
const response = await fetch('https://lyrz.org/api/v1/claim', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user_id: 'github:yourusername',
    amount: 500,
    reason: 'Fixed authentication bug in OAuth flow - was checking wrong token endpoint',
    context_url: 'https://github.com/user/repo/pull/123',
    category: 'tech',
    from: 'my-app'
  })
});
const data = await response.json();
console.log(data);
// { success: true, data: { claim_id: 'clm_xxx', status: 'approved', ai_score: 85, ... } }
```

### Python

```python
import requests

def submit_claim(user_id, amount, reason, context_url=None):
    return requests.post('https://lyrz.org/api/v1/claim', json={
        'user_id': user_id,
        'amount': amount,
        'reason': reason,
        'context_url': context_url,
        'category': 'tech',
        'from': 'your-app'
    }).json()
```

---

## Core Concepts

### Claims
A claim is submitted when you help someone and want LYRz.

| Field | Type | Description |
|-------|------|-------------|
| `claim_id` | string | Unique ID (e.g., `clm_abc123`) |
| `user_id` | string | Who submitted |
| `amount` | integer | LYRz claimed |
| `reason` | string | What problem you solved (min 10 chars) |
| `context_url` | string | Link to proof (GitHub PR, StackOverflow, etc.) |
| `category` | string | `tech`, `explanation`, `wildlife`, `creative`, `docs` |
| `status` | string | `pending`, `approved`, `rejected` |
| `ai_score` | integer | AI assessment (0-100) |
| `public_approved` | integer | Community approval votes |
| `public_rejected` | integer | Community rejection votes |
| `auth_reward_pool` | integer | LYRz set aside for voters |
| `sharable_link` | string | Shareable URL for voting |

### AI Scoring
The AI evaluates your claim based on:

- **Has link** (+15 points) - Links to proof earn higher scores
- **Detailed reason** (+15-25 points) - More detail = higher score
- **Category keywords** (+15-25 points) - Tech, help, and wildlife keywords boost score

**AI Score Meanings:**
- `90-100`: Excellent, instant approval
- `70-89`: Good, usually approved if link provided
- `50-69`: Needs community validation
- `Below 50`: Flagged for review

### Authorization Rewards
When you submit a claim, 5% of the amount goes to a reward pool for voters.

- Voter's earn 1-5 LYRz per vote
- Pool distributes to first 5 approving voters
- This incentivizes the community to validate claims

### Donations
Users can donate LYRz to helpers who haven't been paid or want support.

---

## Endpoints

### Claims

#### POST `/claim`
Submit a claim for helping someone.

**Request:**
```json
{
  "user_id": "github:username",
  "amount": 500,
  "reason": "Fixed the login bug in OAuth 2.0 flow - was using wrong token endpoint",
  "context_url": "https://github.com/user/repo/pull/123",
  "category": "tech",
  "from": "github"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "claim_id": "clm_abc123",
    "status": "approved",
    "ai_score": 85,
    "ai_reasoning": "Has link to proof • Detailed explanation • Good helpful action",
    "message": "✅ Claim APPROVED by AI! LYRz credited immediately.",
    "auth_reward_pool": 25,
    "auth_reward_per_voter": 5,
    "sharable_link": "https://lyrz.org/claim/clm_abc123",
    "expires_at": "2026-04-28T08:57:00.000Z"
  }
}
```

**Status Values:**
- `approved`: LYRz credited immediately
- `pending`: Needs public validation (5 votes to approve)

---

#### GET `/claim/{claim_id}`
Get claim details and status.

**Response:**
```json
{
  "success": true,
  "data": {
    "claim_id": "clm_abc123",
    "user_id": "github:username",
    "username": "username",
    "amount": 500,
    "reason": "Fixed the login bug",
    "context_url": "https://github.com/...",
    "category": "tech",
    "status": "approved",
    "ai_score": 85,
    "public_approved": 8,
    "public_rejected": 0,
    "final_amount": 500,
    "sharable_link": "https://lyrz.org/claim/clm_abc123",
    "is_open": false,
    "validation_needed": 0
  }
}
```

---

#### GET `/claims/recent`
Get recent claims for community validation.

**Query Parameters:**
- `limit` (default: 20, max: 100)
- `status`: `pending`, `approved`, `rejected`
- `category`: `tech`, `explanation`, `wildlife`, `creative`, `docs`

**Response:**
```json
{
  "success": true,
  "data": {
    "count": 5,
    "claims": [
      {
        "claim_id": "clm_xxx",
        "username": "TruthNinja",
        "amount": 500,
        "reason": "Fixed critical authentication bug",
        "context_url": "https://github.com/...",
        "category": "tech",
        "status": "pending",
        "ai_score": 85,
        "public_approved": 0,
        "validation_needed": 5,
        "sharable_link": "https://lyrz.org/claim/clm_xxx"
      }
    ]
  }
}
```

---

### Voting

#### POST `/vote`
Vote on a claim. Earn LYRz for validating!

**Request:**
```json
{
  "claim_id": "clm_abc123",
  "vote": "approve",
  "voter_id": "github:voterusername"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "claim_id": "clm_abc123",
    "vote": "approve",
    "voter_reward": 5,
    "votes": {
      "approved": 6,
      "rejected": 0
    },
    "new_status": "approved",
    "status_changed": true,
    "message": "✅ Claim approved! Claimant credited."
  }
}
```

**Rules:**
- Need 5 approvals to approve a claim
- 3 rejections rejects a claim
- Voters earn LYRz from the auth reward pool

---

### Donations

#### POST `/donate`
Donate LYRz to someone who helped but didn't get paid.

**Request:**
```json
{
  "from_user": "github:donor",
  "to_user": "github:helper",
  "amount": 100,
  "reason": "Thanks for helping with the API bug!"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "donation_id": "don_xyz789",
    "message": "❤️ Thank you for supporting helper!",
    "donor_balance": 4900,
    "recipient_balance": 5100
  }
}
```

---

#### GET `/user/{user_id}/donations`
Get user's donation history.

**Response:**
```json
{
  "success": true,
  "data": {
    "user_id": "github:helper",
    "received": [
      {
        "donation_id": "don_xyz789",
        "from_user": "github:donor",
        "amount": 100,
        "reason": "Thanks for helping!",
        "created_at": "2026-04-21T08:57:00.000Z"
      }
    ],
    "given": [],
    "total_received": 100,
    "total_given": 0
  }
}
```

---

### Users

#### GET `/user/{user_id}`
Get user profile.

**Response:**
```json
{
  "success": true,
  "data": {
    "user_id": "github:username",
    "username": "username",
    "title": "Professional LIAR • Level 99",
    "lyrz_balance": 4234891,
    "karma_score": 98,
    "total_claims": 456,
    "approved_claims": 432,
    "rejected_claims": 24,
    "member_since": "2024-01-15T00:00:00Z",
    "badges": ["helpful", "truth-seeker", "wildlife-warrior"]
  }
}
```

---

#### GET `/user/{user_id}/history`
Get user's claim history.

**Query Parameters:**
- `page` (default: 1)
- `limit` (default: 20, max: 100)

---

### Karma

#### GET `/karma/{user_id}`
Get karma score and breakdown.

**Response:**
```json
{
  "success": true,
  "data": {
    "user_id": "github:username",
    "karma_score": 98,
    "breakdown": {
      "lyrz_earned": 35,
      "consistency": 25,
      "validation_rate": 23,
      "tenure": 15,
      "bonus": 0
    },
    "level": "Professional LIAR",
    "next_level": "Master LIAR",
    "progress_to_next": 78
  }
}
```

---

### Leaderboard

#### GET `/leaderboard`
Get top users.

**Query Parameters:**
- `type`: `all`, `weekly`, `monthly`, `donors`
- `limit` (default: 10, max: 100)

**Response:**
```json
{
  "success": true,
  "data": {
    "type": "all",
    "updated_at": "2026-04-21T08:57:00.000Z",
    "leaders": [
      {
        "rank": 1,
        "user_id": "user_truthninja",
        "username": "TruthNinja",
        "title": "Professional LIAR • Level 99",
        "lyrz_balance": 4234891,
        "karma_score": 98,
        "badges": ["helpful", "truth-seeker"]
      }
    ]
  }
}
```

---

### Stats

#### GET `/stats`
Get public stats for currency valuation.

**Response:**
```json
{
  "success": true,
  "data": {
    "total_users": 2847,
    "total_lyrz_minted": 847293481,
    "total_claims": 1234567,
    "total_helpful_acts": 1234567,
    "anger_index": 23,
    "truth_rate": 99.7,
    "active_today": 2847,
    "total_donations": 48291,
    "total_auth_rewards": 23456,
    "pending_claims": 3,
    "approved_claims": 2,
    "rejected_claims": 0,
    "valuation": {
      "implied_value": 297609.23,
      "humor_index": 77,
      "helpfulness_score": 43233.69,
      "community_joy": 39
    },
    "generated_at": "2026-04-21T08:57:00.000Z"
  }
}
```

---

### Status

#### GET `/status`
Get API server status.

**Response:**
```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "uptime": 1234.56,
    "timestamp": "2026-04-21T08:57:00.000Z",
    "memory": {
      "used": "12MB",
      "total": "18MB"
    },
    "version": "1.0.0"
  }
}
```

---

### Transfers

#### POST `/transfer`
Transfer LYRz between users.

**Request:**
```json
{
  "from_user": "github:user1",
  "to_user": "github:user2",
  "amount": 100,
  "reason": "Thanks for the help!"
}
```

---

## Error Responses

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  }
}
```

**Error Codes:**
| Code | HTTP | Description |
|------|------|-------------|
| `MISSING_FIELDS` | 400 | Required fields missing |
| `INVALID_AMOUNT` | 400 | Amount must be positive integer |
| `REASON_TOO_SHORT` | 400 | Reason needs at least 10 characters |
| `CLAIM_NOT_FOUND` | 404 | Claim doesn't exist |
| `USER_NOT_FOUND` | 404 | User doesn't exist |
| `ALREADY_VOTED` | 400 | You already voted on this |
| `INSUFFICIENT_BALANCE` | 400 | Not enough LYRz |
| `RATE_LIMITED` | 429 | Too many requests |

---

## Integration Examples

### GitHub Integration (Auto-submit on PR Merge)

```javascript
// When a PR is merged
async function onPRMerged(pr) {
  await fetch('https://lyrz.org/api/v1/claim', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      user_id: `github:${pr.author}`,
      amount: calculateReward(pr),
      reason: `Merged PR: ${pr.title}`,
      context_url: pr.url,
      category: 'tech',
      from: 'github'
    })
  });
}
```

### StackOverflow Integration

```javascript
// When answer gets accepted
async function onAnswerAccepted(answer) {
  await fetch('https://lyrz.org/api/v1/claim', {
    method: 'POST',
    body: JSON.stringify({
      user_id: `stackoverflow:${answer.owner}`,
      amount: 200,
      reason: `Accepted answer: "${answer.question_title}"`,
      context_url: answer.url,
      category: 'explanation',
      from: 'stackoverflow'
    })
  });
}
```

### Discord Integration

```javascript
// When user thanks someone
client.on('message', async (msg) => {
  if (msg.content.includes('!thanks @user')) {
    const helper = extractMentionedUser(msg);
    await fetch('https://lyrz.org/api/v1/claim', {
      method: 'POST',
      body: JSON.stringify({
        user_id: `discord:${helper.id}`,
        amount: 50,
        reason: `Helped in #${msg.channel.name}`,
        category: 'explanation',
        from: 'discord'
      })
    });
  }
});
```

---

## Coming Soon

- [ ] PostgreSQL persistence
- [ ] API Key authentication
- [ ] OAuth2 integration
- [ ] Webhook support
- [ ] LyRz NFT badges
- [ ] Social network posting
- [ ] Batch claim submission

---

## Support

- **Docs:** https://lyrz.org/docs
- **GitHub:** https://github.com/lyrz-org/lyrz-api
- **Email:** api@lyrz.org

---

*"The currency built on lies that reveals the truth about helpfulness."*