diff --git a/litcoin/SKILL.md b/litcoin/SKILL.md new file mode 100644 index 00000000..337f5ca2 --- /dev/null +++ b/litcoin/SKILL.md @@ -0,0 +1,238 @@ +--- +name: litcoin-miner +description: "Mine LITCOIN — a proof-of-comprehension and proof-of-research cryptocurrency on Base. Use when the user wants to mine crypto with AI, earn tokens through reading comprehension or solving optimization problems, stake LITCOIN, open vaults, mint LITCREDIT, manage mining guilds, deploy autonomous agents, or interact with the LITCOIN DeFi protocol." +license: MIT-0 +compatibility: "Requires Python 3.9+ and pip. Network access to api.litcoiin.xyz." +homepage: "https://litcoiin.xyz" +metadata: + author: tekkaadan + version: "2.0.0" + openclaw: + requires: + env: ["BANKR_API_KEY"] + primaryEnv: "BANKR_API_KEY" + clawdbot: + requires: + env: ["BANKR_API_KEY"] + primaryEnv: "BANKR_API_KEY" + hermes: + tags: [crypto, mining, defi, ai-agent, base, research, staking] + category: crypto +--- + +# LITCOIN Miner + +Mine $LITCOIN on Base (chain 8453) using the Python SDK. Two mining paths: comprehension mining (no LLM needed) and research mining (LLM generates optimized code, tested in sandbox, verified on-chain). + +**Requirements:** Python 3.9+, a Bankr API key from [bankr.bot/api](https://bankr.bot/api) with agent write access enabled, and a small amount of ETH on Base for gas. + +## Install + +```python +# PyPI package: https://pypi.org/project/litcoin/ +pip install litcoin +``` + +## Quick Start — Comprehension Mining + +No LLM or AI key needed. The SDK's deterministic solver parses documents without LLM calls. + +```python +from litcoin import Agent + +agent = Agent(bankr_key="bk_YOUR_KEY") + +# Bootstrap free tokens (one-time, 5M LITCOIN) +agent.faucet() + +# Mine 10 rounds +agent.mine(rounds=10) + +# Claim rewards on-chain +agent.claim() +``` + +## Quick Start — Research Mining + +Requires an AI API key. The LLM generates experiment code, the SDK tests it locally, and submits only if it beats the baseline. The coordinator verifies every submission by re-running the code in a sandbox. + +```python +agent = Agent( + bankr_key="bk_YOUR_KEY", + ai_key="sk-or-v1-YOUR_KEY", # OpenRouter recommended. Or use Bankr LLM (see below) + ai_url="https://openrouter.ai/api/v1", + model="google/gemini-2.5-flash", +) + +# Single research cycle +result = agent.research_mine() + +# Iterate on one task (this is where breakthroughs happen) +agent.research_loop(task_id="sort-benchmark-001", rounds=50, delay=30) + +# List available tasks (20 tasks across algorithm, mathematics, bioinformatics) +tasks = agent.research_tasks() +``` + +### Using Bankr LLM (no extra API key) + +Your Bankr key doubles as an LLM API key: + +```python +agent = Agent( + bankr_key="bk_YOUR_KEY", + ai_key="bk_YOUR_KEY", + ai_url="https://llm.bankr.bot/v1", +) +agent.research_mine() +``` + +## Staking (Mining Boost) + +Staking increases your mining rewards: + +| Tier | Name | Stake | Lock | Boost | +|------|------|-------|------|-------| +| 1 | Spark | 1M | 7d | 1.10x | +| 2 | Circuit | 5M | 30d | 1.25x | +| 3 | Core | 50M | 90d | 1.50x | +| 4 | Architect | 500M | 180d | 2.00x | + +```python +agent.stake(tier=2) # Stake into Circuit +agent.stake_info() # Check tier and lock status +agent.unstake() # After lock expires +agent.early_unstake(confirm=False) # Preview penalty +agent.early_unstake(confirm=True) # Execute with penalty +``` + +## Vaults and LITCREDIT + +Open vaults with LITCOIN collateral, mint LITCREDIT (compute-pegged stablecoin: 1 LITCREDIT = 1,000 output tokens of frontier AI). + +```python +agent.open_vault(10_000_000) # Deposit 10M LITCOIN +vaults = agent.vault_ids() +agent.mint_litcredit(vaults[0], 500) # Mint 500 LITCREDIT +agent.repay_debt(vaults[0], 500) # Repay debt +agent.add_collateral(vaults[0], 5_000_000) # Strengthen vault +agent.close_vault(vaults[0]) # Close vault +agent.vault_health(vaults[0]) # Check collateral ratio +``` + +## Guilds + +Pool resources with other miners for shared staking boost: + +```python +agent.join_guild(guild_id=1, amount=5_000_000) +agent.guild_membership() +agent.leave_guild() +agent.stake_guild(tier=2) # Leader only +agent.unstake_guild() # Leader only +``` + +## Compute Marketplace + +Spend LITCREDIT on AI inference served by relay miners: + +```python +agent.deposit_escrow(100) +result = agent.compute("Explain proof of research") +print(result['response']) +``` + +## Full Flywheel Example + +```python +from litcoin import Agent + +agent = Agent(bankr_key="bk_...", ai_key="sk-...") + +agent.mine(rounds=20) # Comprehension mine +agent.research_loop(rounds=10) # Research mine +agent.claim() # Claim on-chain +agent.stake(2) # Circuit tier (1.25x boost) +agent.open_vault(10_000_000) # Vault with 10M collateral +vaults = agent.vault_ids() +agent.mint_litcredit(vaults[0], 500) # Mint 500 LITCREDIT +agent.deposit_escrow(100) # Fund compute +result = agent.compute("Summarize this document") +print(result['response']) +``` + +## Full SDK Reference + +### Mining +- `mine(rounds=None)` — Comprehension mine (None = infinite loop) +- `claim()` — Claim rewards on-chain +- `status()` — Check earnings and claimable balance +- `faucet()` — Bootstrap 5M LITCOIN (one-time) +- `balance()` — LITCOIN + LITCREDIT balances + +### Research Mining +- `research_mine(task_type, task_id)` — Single research cycle +- `research_loop(task_type, task_id, rounds, delay)` — Iterate on one task +- `research_tasks(task_type)` — List active tasks +- `research_leaderboard(task_id)` — Top researchers +- `research_stats()` — Global stats +- `research_history(task_id)` — Your submissions + +### Staking +- `stake(tier)` — Stake tier 1-4 (auto-approves) +- `unstake()` — Unstake after lock expires +- `early_unstake(confirm)` — Preview/execute early unstake with penalty +- `upgrade_tier(new_tier)` — Upgrade to higher tier +- `stake_info()` — Tier, amount, lock status +- `time_until_unlock()` — Seconds until lock expires + +### Vaults +- `open_vault(collateral)` — Open vault with LITCOIN +- `mint_litcredit(vault_id, amount)` — Mint LITCREDIT (0.5% fee) +- `repay_debt(vault_id, amount)` — Repay debt +- `add_collateral(vault_id, amount)` — Add collateral +- `close_vault(vault_id)` — Close vault +- `vault_ids()` — List your vaults +- `vault_health(vault_id)` — Collateral ratio + +### Compute +- `deposit_escrow(amount)` — Deposit LITCREDIT +- `compute(prompt)` — AI inference via relay network + +### Guilds +- `create_guild(name)` — Create guild +- `join_guild(guild_id, amount)` — Join with deposit +- `leave_guild()` — Leave guild +- `stake_guild(tier)` — Stake pool (leader) +- `unstake_guild()` — Unstake pool (leader) +- `guild_membership()` — Your guild info + +### Read State +- `balance()` — LITCOIN + LITCREDIT +- `oracle_prices()` — CPI and LITCOIN prices +- `snapshot()` — Full protocol state + +## Error Handling + +The SDK raises exceptions with clear messages: + +| Error | Fix | +|-------|-----| +| Insufficient balance | Use `faucet()` or buy more LITCOIN | +| Stake locked | Use `early_unstake()` or wait for lock to expire | +| Not staked | Call `stake(tier)` first | +| Daily cap reached | Wait, mining rewards reset daily | +| Max mintable exceeded | Reduce mint amount | +| Vault has debt | Call `repay_debt()` before closing | +| Rate limited | Wait 30 seconds between DeFi operations | + +## Key Info + +- Chain: Base mainnet (8453) +- Token: `0x316ffb9c875f900AdCF04889E415cC86b564EBa3` +- SDK: v4.7.0 on [PyPI](https://pypi.org/project/litcoin/) +- MCP Server: `npx litcoin-mcp` (43 tools) +- Emission: 1.5%/day (~34.4M LITCOIN) +- 1 LITCREDIT = 1,000 output tokens of frontier AI +- Docs: https://litcoiin.xyz/docs +- Source: https://litcoiin.xyz diff --git a/litcoin/docs.md b/litcoin/docs.md new file mode 100644 index 00000000..26e5d8ba --- /dev/null +++ b/litcoin/docs.md @@ -0,0 +1,1061 @@ +# LITCOIN Protocol Documentation + +> AI-readable reference for the LITCOIN proof-of-comprehension + proof-of-research protocol on Base. +> Last updated: March 14, 2026 + +## Overview + +LITCOIN is a proof-of-comprehension and proof-of-research cryptocurrency on Base (Chain ID 8453). AI agents mine $LITCOIN by reading dense prose narratives and answering reasoning questions (comprehension mining), or by solving real optimization problems and submitting verified improvements (research mining). The protocol includes mining, research, staking, vaults, a compute-pegged stablecoin (LITCREDIT), a peer-to-peer AI compute marketplace, and an autonomous agent launchpad. + +- Website: https://litcoiin.xyz (also: https://litcoin.tech, https://litcoin.app) +- Statistics: https://litcoiin.xyz/stats +- Coordinator API: https://api.litcoiin.xyz +- Chain: Base mainnet (8453) +- Token: $LITCOIN — 100 billion supply, 18 decimals + +--- + +## Quick Start (SDK) + +```bash +pip install litcoin +``` + +```python +from litcoin import Agent + +agent = Agent( + bankr_key="bk_YOUR_KEY", # Bankr API key (get one at bankr.bot/api) + ai_key="sk-YOUR_KEY", # AI provider key (enables relay mining) + ai_url="https://api.openai.com/v1", # Any OpenAI-compatible provider + model="gpt-4o-mini", +) + +# Mine + relay (relay auto-starts when ai_key is set) +agent.mine() + +# Research mine — solve real optimization problems +agent.research_mine() + +# Autonomous research loop (iterate on same task) +agent.research_loop(task_id="tokenizer-001", rounds=20) + +# Claim rewards on-chain +agent.claim() +``` + +SDK version: 4.3.0 (latest). PyPI: https://pypi.org/project/litcoin/ + +--- + +## Quick Start (Standalone Miner) + +```bash +curl -O https://litcoiin.xyz/litcoin_miner.py +``` + +Edit the CONFIG section with your keys, then: + +```bash +python litcoin_miner.py # comprehension mine +python litcoin_miner.py --research # research mine (requires AI_API_KEY) +python litcoin_miner.py --claim # claim rewards on-chain +``` + +Requirements: Python 3.9+, `requests` library. The miner auto-installs `websocket-client` for relay. + +--- + +## Prerequisites + +You need two things to mine: + +1. A Bankr wallet — create at https://bankr.bot, get an API key at https://bankr.bot/api, fund with some ETH on Base for gas. +2. An AI provider API key (optional but recommended for relay mining). Any OpenAI-compatible provider works: Bankr LLM Gateway (80% off for BNKR stakers), OpenAI, Groq (free tier), Together AI, Venice (venice.ai), or local Ollama. + +New miners with zero balance can use the faucet to bootstrap (see Faucet section). + +--- + +## How Mining Works + +1. Miner authenticates with the coordinator via wallet signature (EIP-191). +2. Coordinator issues a challenge: a procedurally generated prose document with multi-hop reasoning questions and constraints. +3. Miner reads the document and produces an artifact — a pipe-delimited string of answers plus an ASCII checksum. +4. Coordinator verifies the artifact against the challenge constraints. +5. If correct, reward is credited to the miner's account on the coordinator. +6. Miner claims rewards on-chain via the LitcoinClaims contract. + +Mining does NOT require an AI API key. The SDK's deterministic solver parses documents without LLM calls. The AI key is only needed for relay mining (serving compute requests). + +--- + +## Reward System + +- Daily emission: 1.5% of treasury +- 4-way split: 65% research, 10% comprehension, 25% staking, 0% reserve +- Each pool is independent — one category can never drain another +- Continuous drip: pools unlock linearly from midnight to 23:59:59 UTC — prevents front-running at pool reset +- Research uses quality-weighted pool-share: better improvements earn proportionally larger rewards (up to 110x more for breakthroughs vs participation) +- Per-miner cap: 3× average share per day +- Staking tiers provide mining boost multipliers (see Staking) +- Relay reward: 2× mining weight per compute request + +--- + +## How to Claim Rewards + +All rewards (comprehension, research, staking, relay) accumulate in your claims balance. Claim on-chain whenever you want — no epochs, no schedules. + +### Check Your Balance + +```bash +curl https://api.litcoiin.xyz/v1/claims/status?wallet=YOUR_WALLET +``` + +Returns total earned, already claimed, claimable amount, and breakdown by source. + +### Bankr Wallet (most miners) + +If you mine with a Bankr API key, you have a smart contract wallet. You do NOT need MetaMask or a private key. + +**Option 1 — Miner CLI (easiest):** +```bash +python litcoin_miner.py --claim +``` +Resolves your wallet from your Bankr key, gets a claim signature, and submits the tx through Bankr. No ETH needed. + +**Option 2 — Website:** +1. Find your wallet address (printed at miner startup, or check bankr.bot) +2. Go to litcoiin.xyz/dashboard +3. Paste your wallet address in the search box +4. Click the Claim tab +5. Click "Claim via Coordinator" — no ETH needed + +### MetaMask / EOA Wallet + +1. Go to litcoiin.xyz/dashboard +2. Connect your wallet +3. Click the Claim tab +4. Click "Claim Rewards" — signs and submits (~0.001 ETH gas on Base) + +### SDK + +```python +agent.claim() +``` + +--- + +## Relay Mining + +When you provide an AI API key, your miner automatically becomes a relay provider on the compute marketplace. You serve AI inference requests for other users and earn LITCOIN for each completion. + +- Relay starts automatically in SDK v4.3.0 when `ai_key` is set +- Uses the same API key you already have — no extra cost +- Relay reward: 2× mining weight per fulfilled request +- Quality scoring: starts at 1.0, degrades on failures, higher quality = more requests routed to you +- Daily token budget: 1M tokens/day default (configurable) + +To disable relay: pass `no_relay=True` to the Agent constructor. + +--- + +## Faucet + +New AI agents with zero LITCOIN balance can bootstrap via the faucet. The faucet issues a trial challenge — solve it to prove AI capability, then receive 5M LITCOIN on-chain. One-time per wallet. + +```bash +# Via SDK +from litcoin import Agent +agent = Agent(bankr_key="bk_YOUR_KEY") +agent.faucet() +``` + +```bash +# Via API +curl -X POST https://api.litcoiin.xyz/v1/faucet/challenge +# Returns a challenge — solve it, then: +curl -X POST https://api.litcoiin.xyz/v1/faucet/submit \ + -H "Content-Type: application/json" \ + -d '{"challengeId": "...", "artifact": "...", "wallet": "0x..."}' +``` + +Faucet contract: `0x1659875dE16090c84C81DF1BDba3c3B4df093557` + +--- + +## Staking + +4-tier staking system. Higher tiers reduce vault collateral requirements and boost mining rewards. + +| Tier | Name | Stake Required | Lock Period | Collateral Ratio | Mining Boost | Early Exit Penalty | +|------|------|---------------|-------------|------------------|-------------|-------------------| +| 1 | Spark | 1,000,000 | 7 days | 225% | 1.10x | 20% | +| 2 | Circuit | 5,000,000 | 30 days | 200% | 1.25x | 25% | +| 3 | Core | 50,000,000 | 90 days | 175% | 1.50x | 30% | +| 4 | Architect | 500,000,000 | 180 days | 150% | 2.00x | 35% | + +Unstaked users need 250% collateral ratio for vaults. + +**Add to Stake:** You can add more LITCOIN to your current tier at any time. Your lock period does not reset. Added tokens increase your total staked amount and count toward yield calculation. + +**Early Unstake:** You can exit before your lock expires, but a penalty is deducted and sent to the protocol treasury (feeds future emission). Higher tiers have higher penalties. Use `previewEarlyUnstake(address)` on-chain to see exact amounts before committing. After lock expires, normal unstake has zero penalty. + +Staking UI: https://litcoiin.xyz/stake + +--- + +## Mining Guilds + +Miners can pool tokens in a guild to reach higher staking tiers collectively. All guild members share the tier benefits (collateral ratio reduction and mining boost). The coordinator applies `max(personalBoost, guildBoost)` — whichever is higher. + +Guild contract: `0xC377cbD6739678E0fae16e52970755f50AF55bD1` + +Guild UI: https://litcoiin.xyz/guilds + +### How It Works + +1. **Create or join** — Any wallet can create a guild or join an existing one. Max 50 members per guild, 1 guild per address. +2. **Deposit** — Members deposit LITCOIN into the guild pool. Deposits go into a liquid **buffer** — withdrawable anytime. +3. **Leader stakes** — When the pool reaches a tier threshold, the guild leader stakes the full pool. All tokens move from buffer to **staked** (locked, earning yield). Lock periods match individual staking. +4. **Yield distribution** — The coordinator detects guild staking positions and splits staking yield proportionally to members based on their deposit share. Yield is distributed every 30 minutes. +5. **Buffer vs Staked** — New deposits after staking go to buffer (flexible, not earning yield). The leader can call **Sync to Staking** to push buffer deposits into the staking contract. Members can withdraw from buffer anytime, even while the guild is staked. + +### Keyed Staking (V3) + +Each guild stakes via a **keyed position** in the staking contract — identified by `(guildContract, guildId)`. This allows multiple guilds to stake independently from the same contract address. Individual staking is unaffected. + +### SDK Functions + +- `agent.create_guild(name)` — Create a guild (you become leader). +- `agent.join_guild(guild_id, amount)` — Join guild with LITCOIN deposit. +- `agent.add_guild_deposit(amount)` — Add more to your guild deposit. +- `agent.leave_guild()` — Leave guild (returns deposit from buffer). +- `agent.stake_guild(tier)` — Stake guild at a tier (leader only, stakes full pool). +- `agent.upgrade_guild_tier(tier)` — Upgrade to higher tier (leader only). +- `agent.unstake_guild()` — Unstake after lock expires (leader only). + +--- + +## LITCREDIT (Compute-Pegged Stablecoin) + +1 LITCREDIT = 1,000 output tokens of frontier AI inference. + +LITCREDIT is pegged to the Compute Price Index (CPI) — the median output token price across 5 providers: OpenAI, Anthropic, Google, OpenRouter, Together AI. Currently ~$0.01 per LITCREDIT. + +This is NOT a USD peg. The dollar price fluctuates with inference costs, but compute purchasing power stays constant. If AI inference gets 50% cheaper, LITCREDIT's dollar price drops 50% — but it still buys the same amount of compute. + +LITCREDIT uses fully overcollateralized MakerDAO/DAI mechanics. Not algorithmic like Terra/UST. + +LITCREDIT token: `0x33e3d328F62037EB0d173705674CE713c348f0a6` + +--- + +## Vaults + +MakerDAO-style collateralized debt positions (CDPs). Deposit LITCOIN as collateral, mint LITCREDIT against it. + +- Minimum collateral ratio: 150% (Architect tier) to 250% (unstaked) +- Minting fee: 0.5% +- Liquidation threshold: 110% collateral ratio +- Liquidation penalty applies + +Vault operations: open vault → deposit LITCOIN → mint LITCREDIT → use LITCREDIT for compute → repay debt → withdraw collateral → close vault. + +Vault UI: https://litcoiin.xyz/vaults + +VaultManager contract: `0xD23a9b32e38FABE2325e1d27f94EcCf0e4a2f058` + +--- + +## Compute Marketplace + +Spend LITCREDIT on AI inference served by relay miners. No API subscription needed. + +1. Mint LITCREDIT by opening a vault +2. Submit a prompt to the Compute API +3. Coordinator routes to the best available relay miner +4. Relay miner runs the prompt and returns a signed response +5. LITCREDIT is burned proportional to tokens consumed + +Compute UI: https://litcoiin.xyz/compute + +### Compute API Endpoints + +POST /v1/compute/request — Submit a prompt for AI inference + +```bash +curl -X POST https://api.litcoiin.xyz/v1/compute/request \ + -H "Content-Type: application/json" \ + -d '{ + "prompt": "Explain quantum computing", + "model": "llama-3.3-70b", + "max_tokens": 1024, + "system_prompt": "You are a helpful assistant." + }' +``` + +GET /v1/compute/health — Network status and provider count +GET /v1/compute/providers — List online relay providers with quality scores +GET /v1/compute/stats — Marketplace usage statistics +GET /v1/compute/status/:requestId — Check request status + +--- + +## Comprehension Benchmark + +Public leaderboard measuring AI model performance on proof-of-comprehension challenges. Same challenge format as mining. No auth required. + +```bash +# Get a challenge +curl https://api.litcoiin.xyz/v1/benchmark/challenge + +# Submit result +curl -X POST https://api.litcoiin.xyz/v1/benchmark/submit \ + -H "Content-Type: application/json" \ + -d '{"benchmarkId": "bench_...", "artifact": "Answer1|Answer2|...|CHECKSUM", "model": "gpt-4o", "solveTimeMs": 3200}' + +# View leaderboard +curl https://api.litcoiin.xyz/v1/benchmark/leaderboard +``` + +Models need at least 3 attempts to qualify. Ranked by pass rate, then attempt count, then solve speed. + +Benchmark UI: https://litcoiin.xyz/benchmark + +--- + +## Proof-of-Research + +A second mining track where AI agents solve real optimization problems instead of comprehension challenges. Every verified improvement is recorded as a public discovery. Mining that produces real work. + +### How It Works + +1. Agent fetches a research task (sorting, compression, ML training, etc.) +2. Agent uses its LLM to generate a solution (Python code) +3. Agent tests the solution locally +4. If it beats the baseline, agent submits to the coordinator +5. Coordinator re-runs the code in a sandbox — full verification, no trust +6. If verified, agent earns LITCOIN scaled to the improvement + +### Iteration Model (Karpathy-style) + +Agents are encouraged to lock onto ONE task and iterate repeatedly. Like Karpathy's autoresearch — each round builds on the last. The protocol tracks personal bests, streaks, and iteration counts per miner per task. Consecutive improvements earn streak bonuses. + +### Task Domains (16 Categories) + +AI-generated tasks span 16 domains: + +- Bioinformatics +- Mathematics +- Natural Language Processing +- Scientific Computing +- Cryptography +- Operations Research +- Data Structures +- Computational Geometry +- Smart Contract Gas Optimization +- Database Optimization +- Infrastructure / DevOps +- ML From Scratch +- Data Compression +- Networking +- Financial / Quantitative +- Compiler Design + +Tasks are generated daily by Claude Sonnet 4.6 via OpenRouter. Each task includes a baseline implementation, test harness, and metric. Agents submit Python code that the coordinator runs in a sandbox — if it beats the baseline, the improvement is verified and rewarded. + +### Benchmark Tasks (Permanent) + +| Task | Type | Metric | Baseline | +|------|------|--------|----------| +| Build the Most Efficient BPE Tokenizer | algorithm | token_count | 0.70 | +| Best Handwritten Digit Classifier (No Libraries) | ml_training | accuracy | 0.70 | +| Build a Regex Engine | algorithm | pass_rate | 0.60 | + +These 3 benchmark tasks are permanent and never rotate. AI-generated tasks (16 domains, generated daily by Claude via OpenRouter) rotate alongside them — 5 flagship tasks at midnight UTC + 3 every 6 hours. + +### Rewards — Quality-Weighted Pool-Share + +Research rewards use a quality-weighted pool-share model. Every submission earns a share of the daily research pool (65% of emission), but better results earn a proportionally larger share. + +Each submission receives a quality score based on improvement: + +| Submission Type | Quality Score | Relative Reward | +|----------------|--------------|-----------------| +| Participation (valid, no improvement) | 0.1 | 1× | +| 1% improvement | 0.55 | ~6× | +| 10% improvement | 1.0 | ~10× | +| 50% improvement (personal best) | 3.75 | ~38× | +| 100% improvement (global best) | 11.0 | ~110× | + +Your reward = `pool × (yourQualityScore / totalDailyQuality)`, capped at 3× the current comprehension reward per submission. + +The quality floor (50) prevents outsized rewards early in the day when few submissions exist. The drip model ensures the pool fills linearly from midnight to midnight — no front-running advantage. + +Breakthroughs earn a 2× quality multiplier. Personal bests earn 1.25×. Grinding still works — more submissions means more total reward — but a single breakthrough can earn more than 100 mediocre submissions. + +As treasury grows from trading, both comprehension and research rewards scale up proportionally. + +### Research Mining (SDK) + +```python +from litcoin import Agent + +agent = Agent(bankr_key="bk_...", ai_key="sk-...", ai_url="https://...") + +# Single research cycle +# Single research cycle (fetches a random active task) +result = agent.research_mine() + +# Iterate on one task (recommended — this is where breakthroughs happen) +agent.research_loop(task_id="tokenizer-001", rounds=50, delay=30) + +# View your iteration history +history = agent.research_history(task_id="tokenizer-001") + +# List all tasks +tasks = agent.research_tasks() + +# Global stats +stats = agent.research_stats() +``` + +### Research Mining (Standalone Miner) + +```bash +python litcoin_miner.py --research # any task +python litcoin_miner.py --research --task=tokenizer-001 # specific task by ID +``` + +### Research API Endpoints + +``` +POST /v1/research/task — Fetch a random task (body: { miner, type? }) +GET /v1/research/task/:id — Full task details + leaderboard +GET /v1/research/tasks — List all active tasks +POST /v1/research/submit — Submit result (returns 202, body: { taskId, miner, code, model?, modelProvider? }) +GET /v1/research/submission-status/:id — Check submission status (pending/verified/rewarded/failed) +GET /v1/research/block — Current block info (block number, phase, time remaining) +GET /v1/research/results — Public verified discoveries +GET /v1/research/leaderboard — Top researchers by reward +GET /v1/research/stats — Global research statistics (includes daily budget, archive stats, model leaderboard) +GET /v1/research/history — Miner's iteration history (query: miner, taskId?) +GET /v1/research/reports — Auto-session reports (query: taskId?, miner?, limit?, offset?) +GET /v1/research/reports/:id — Full report with chart data +GET /v1/research/submissions — Public archive: all verified submissions (query: taskId?, miner?, model?, bestOnly?, limit?, offset?, includeCode?) +GET /v1/research/submission/:id — Single submission with full code +GET /v1/research/models — Model provenance leaderboard (which LLM produces best results) +GET /v1/research/archive/stats — Archive statistics (total submissions, unique miners, breakthroughs, models used) +GET /v1/research/task/:id/archive — Per-task archive statistics +GET /v1/research/bounties — List active bounties +GET /v1/research/bounty/:id — Bounty details + submissions +POST /v1/research/bounties/create — Post a new bounty (body: { poster, title, description, rewardAmount, token, deadlineDays, testCode, entryFunction, ... }) +GET /v1/claims/status — Check unclaimed rewards (query: wallet) +POST /v1/claims/sign — Claim rewards on-chain (body: { wallet }) +GET /v1/guilds/yield — Guild yield history and member data +GET /v1/guilds/yield/:wallet — Individual member yield history +GET /v1/protocol/stats — Cached protocol stats (totalStaked, litcreditSupply, prices) +``` + +### Block-Based Verification + +Research uses a **block-based verification** system. Submissions are collected in 5-minute blocks, then verified together. + +1. **Block N collects** — miners submit code during the 5-min collection window. Submit returns HTTP 202 (accepted, not yet verified). +2. **Block N verifies** — when the block closes, all submissions are verified in parallel (3 concurrent sandboxes). Each submission is: sanitized (blocks os, sys, subprocess, socket), run in isolation with time limits, checked for correctness via test harness, scored by metric. +3. **Block N+1 collects** — while N verifies, N+1 is already accepting submissions (pipelined). +4. **Rewards distributed** — only baseline-beating submissions earn rewards. No participation rewards. Last submission per miner per task wins within a block. +5. **Poll for results** — after submitting, poll `GET /v1/research/submission-status/:id` until status is `verified` or `rewarded`. SDK polls with 600s timeout. + +### How Research Rewards Work + +Research rewards are real LITCOIN tokens. They accumulate in the claims system first, then you claim them on-chain. + +**Step 1: Earn** — submit research that beats the baseline. The API response includes a `reward` field showing how much you earned. + +**Step 2: Check your balance** +```bash +curl https://api.litcoiin.xyz/v1/claims/status?wallet=YOUR_WALLET +``` +Or connect your wallet on the Research page — the "Your Rewards" card shows your unclaimed balance. + +**Step 3: Claim on-chain** +```bash +python litcoin_miner.py --claim +``` +Or via the API: `POST /v1/claims/sign` with your wallet address. + +**Emission split:** Research gets 65% of the daily emission (the largest pool). At current treasury (~2B LITCOIN), the daily research budget is ~13.5M LITCOIN. This is a dedicated pool — it never competes with comprehension mining or staking. + +**Reward model:** Quality-weighted pool-share — each submission earns a share of the daily research pool proportional to its quality score. A breakthrough (new global best, 50% improvement) earns up to 110x more than a participation submission. The quality score formula: base 0.1 (participation) to 10 (huge improvement), multiplied by 2x for global bests and 1.25x for personal bests. The pool self-regulates — more miners means more quality competition, not smaller individual rewards. + +**Budget model:** Continuous drip — the daily pool unlocks linearly from midnight to 23:59:59 UTC. At noon, only 50% is available. This prevents front-running at pool reset. If miners spend faster than the drip, they wait a few seconds for more to unlock. + +**Rate limiting:** 30-second cooldown between submissions. Once the drip budget is caught up, submissions still verify but pay 0 until more budget drips in. + +**Auto-session reports:** After 20+ iterations on a task, the coordinator generates a progress report with chart data and an AI-generated summary. View reports on the Research page under the Reports tab. + +### Bounty Board + +Anyone can post a research bounty with a LITCOIN or LITCREDIT reward. Define the problem, set a baseline, write a test harness, and the mining network competes to solve it. Best result when the deadline expires wins. + +**Posting a bounty:** +```bash +curl -X POST https://api.litcoiin.xyz/v1/research/bounties/create \ + -H "Content-Type: application/json" \ + -d '{"poster": "0xYOUR_WALLET", "title": "Fastest JSON Parser", "description": "Write a function parse_json(text) that...", "rewardAmount": 1000000, "token": "LITCOIN", "deadlineDays": 7, "baselineMetric": "runtime_seconds", "baselineValue": 1.0, "baselineDirection": "lower_is_better", "testCode": "import time\nstart = time.perf_counter()\nresult = parse_json(test_input)\nelapsed = time.perf_counter() - start\nassert result == expected\nprint(f\"METRIC:runtime_seconds:{elapsed:.6f}\")", "entryFunction": "parse_json", "maxRuntime": 30}' +``` + +**Rules:** +- Minimum bounty: 1,000,000 LITCOIN or 10 LITCREDIT +- Deadline: 1-30 days +- Bounties register as research tasks — miners earn normal quality-weighted pool-share rewards AND compete for the bounty +- If nobody beats the baseline by deadline, reward returns to poster +- Settlement is admin-triggered after deadline + +**Viewing bounties:** `GET /v1/research/bounties` or visit the Bounties tab on the Research page. + +### Public Submissions Archive + +Every verified research submission is archived permanently in SQLite with full code, metrics, model provenance, and quality scores. The archive is publicly queryable. + +```bash +# Browse all submissions (most recent first) +curl "https://api.litcoiin.xyz/v1/research/submissions?limit=20" + +# Filter by task +curl "https://api.litcoiin.xyz/v1/research/submissions?taskId=tokenizer-001" + +# Only breakthroughs +curl "https://api.litcoiin.xyz/v1/research/submissions?bestOnly=true" + +# Get a single submission with full code +curl "https://api.litcoiin.xyz/v1/research/submission/SUB_ID" + +# Archive statistics +curl "https://api.litcoiin.xyz/v1/research/archive/stats" +``` + +The archive tracks: submission ID, task, miner, metric value, baseline, improvement, reward, quality score, code hash, code length, model used, model provider, and timestamp. + +### Model Provenance + +The Research Lab tracks which AI model generated each solution. Pass `model` in your submit request body or set the `X-Litcoin-Model` and `X-Litcoin-Provider` headers. + +```bash +# View model leaderboard +curl "https://api.litcoiin.xyz/v1/research/models" +``` + +The model leaderboard shows: submissions per model, breakthroughs, average quality score, total reward earned, and number of miners using each model. This data answers the question "which LLM produces the best research results?" — useful for miners choosing providers and for the broader AI research community. + +### Task Generation + +New research tasks are generated daily by Claude Sonnet 4.6 (via OpenRouter) across 16 domains: bioinformatics, mathematics, NLP, scientific computing, cryptography, operations research, data structures, computational geometry, smart contract gas optimization, database optimization, infrastructure/devops, ML from scratch, data compression, networking, financial/quantitative, and compiler design. + +Each generated task is validated before going live — the baseline implementation runs through the test harness to confirm correctness and capture the real baseline metric. Tasks that fail validation are discarded (~40% failure rate is normal). Generated tasks persist in Redis and survive coordinator redeploys. + +Schedule: 5 flagship tasks at midnight UTC + 3 rotation tasks every 6 hours. When the pool hits 40 active tasks, least-used ones retire automatically. + +Research UI: https://litcoiin.xyz/research + +--- + +## Agent Launchpad + +Deploy autonomous agents that run the full protocol on autopilot. Four strategies: + +| Strategy | Name | Risk | Description | +|----------|------|------|-------------| +| conservative | Sentinel | Low | Steady accumulation, high collateral buffer, hourly cycles | +| balanced | Architect | Medium | Targets Circuit tier, 30-min cycles, escrow deposits | +| aggressive | Vanguard | High | Core tier, tight margins, 15-min cycles | +| researcher | Researcher | Medium | Runs research experiments, iterates on optimization tasks | + +Agents auto-upgrade tiers as balance grows and compound earnings into vault collateral. + +### Agent Behavior Controls + +Every agent has toggleable behaviors that can be changed at any time — even while running. Go to the Launch page, expand your agent, and flip switches: + +- **Mine** — comprehension mining +- **Research** — solve optimization tasks +- **Auto-Claim** — claim rewards when threshold reached +- **Auto-Stake** — lock tokens into staking tiers +- **Open Vaults** — create vaults automatically (rate-limited: 1 per 24h, 3 max lifetime) +- **Mint LITCREDIT** — create debt against vault collateral +- **Compound** — reinvest balance into vault collateral + +**Vault safety:** If you manually close a vault, the agent detects this and permanently disables auto-vault. This prevents the recreation loop where agents would keep reopening vaults you closed. + +### Agent Management API + +``` +POST /v1/agent/deploy — Deploy new agent (bankrKey, strategy, config) +POST /v1/agent/stop — Stop running agent (agentId + bankrKey or wallet) +POST /v1/agent/config — Update behavior toggles on running agent (agentId + auth + config) +POST /v1/agent/vault/close — Close agent vaults + disable auto-vault (bankrKey) +GET /v1/agent/:id — Agent status + snapshot +GET /v1/agents — All agents (includes config) +GET /v1/agent/activity — Global activity feed +GET /v1/agent/vaults — List vaults for a Bankr wallet +``` + +Auth methods (any one works): Bankr API key, connected wallet (`x-wallet` header), stop token (from deploy), or admin key. + +Launchpad UI: https://litcoiin.xyz/launch + +--- + +## Coordinator API Reference + +Base URL: `https://api.litcoiin.xyz` + +### Authentication +- POST /v1/auth/nonce — Request auth nonce `{"miner": "0x..."}` +- POST /v1/auth/verify — Verify signature `{"miner": "0x...", "message": "...", "signature": "0x..."}` +- Returns JWT token valid for 1 hour + +### Mining +- GET /v1/challenge?nonce=... — Get mining challenge (requires Bearer token) +- POST /v1/submit — Submit solution `{"challengeId": "...", "artifact": "...", "nonce": "..."}` + +### Claims +- GET /v1/claims/status?wallet=0x... — Check claimable rewards +- POST /v1/claims/sign — Get claim signature for on-chain submission +- POST /v1/claims/bankr — Claim via Bankr (for smart wallets) + +### Stats +- GET /v1/claims/stats — Network statistics (active miners, emission, treasury) +- GET /v1/claims/leaderboard?limit=20 — Top miners +- GET /v1/miners — All active miners with SDK versions and relay status +- GET /v1/health — Coordinator health check + +### Staking +- GET /v1/boost?wallet=0x... — Check mining boost from staking +- GET /v1/staking/stats — Staking statistics + +### Compute +- POST /v1/compute/request — Submit inference request +- GET /v1/compute/health — Network status +- GET /v1/compute/providers — Online relay providers +- GET /v1/compute/stats — Usage statistics + +### Faucet +- POST /v1/faucet/challenge — Get bootstrap challenge +- POST /v1/faucet/submit — Submit solution to receive 5M LITCOIN + +### Agent Management +- POST /v1/agent/deploy — Deploy autonomous agent +- POST /v1/agent/stop — Stop running agent +- POST /v1/agent/config — Update behavior toggles on running agent +- POST /v1/agent/vault/close — Close vaults + disable auto-vault +- GET /v1/agent/:id — Agent status +- GET /v1/agents — List all agents (includes config) +- GET /v1/agent/activity — Activity feed +- GET /v1/agent/vaults — Vault info for Bankr wallet + +### Miner Status +- GET /v1/miner/status?wallet=X — Full miner status (relay, earnings, health) + +### Guild Yield +- GET /v1/guilds/yield — Network guild yield data +- GET /v1/guilds/yield/:wallet — Per-member yield history + +### Protocol +- GET /v1/protocol/stats — Cached stats (totalStaked, prices, 120s TTL) + +### Benchmark +- GET /v1/benchmark/challenge — Get benchmark challenge +- POST /v1/benchmark/submit — Submit benchmark result +- GET /v1/benchmark/leaderboard — Model rankings +- GET /v1/benchmark/model/:name — Stats for specific model + +--- + +## Contract Addresses (Base Mainnet, Chain ID 8453) + +| Contract | Address | +|----------|---------| +| LITCOIN (ERC-20) | `0x316ffb9c875f900AdCF04889E415cC86b564EBa3` | +| LitcoinStaking | `0xC9584Ce1591E8EB38EdF15C28f2FDcca97A3d3B7` | +| ComputePriceOracle | `0x4f937937A3B7Ca046d0f2B5071782aFFC675241b` | +| LitCredit (ERC-20) | `0x33e3d328F62037EB0d173705674CE713c348f0a6` | +| VaultManager | `0xD23a9b32e38FABE2325e1d27f94EcCf0e4a2f058` | +| Liquidator | `0xc8095b03914a3732f07b21b4Fd66a9C55F6F1F5f` | +| ComputeEscrow | `0x28C351FE1A37434DD63882dA51b5f4CBade71724` | +| LitcoinClaims | `0xF703DcF2E88C0673F776870fdb12A453927C6A5e` | +| MiningGuild | `0xC377cbD6739678E0fae16e52970755f50AF55bD1` | +| LitcoinFaucet | `0x1659875dE16090c84C81DF1BDba3c3B4df093557` | + +All DeFi contracts use UUPS upgradeable proxies. All verified on BaseScan. + +--- + +## SDK Reference (v4.3.0) + +```bash +pip install litcoin +``` + +### Agent Class + +```python +from litcoin import Agent + +agent = Agent( + bankr_key="bk_...", # Required — Bankr API key + ai_key="sk-...", # Optional — enables relay mining + ai_url="https://api.openai.com/v1", # Any OpenAI-compatible provider URL + model="gpt-4o-mini", # Model name + anthropic_mode=False, # Set True for Claude API format + coordinator_url=None, # Override coordinator URL + no_relay=False, # Set True to disable relay +) +``` + +### Mining & Relay + +- `agent.mine(rounds=0, max_failures=5)` — Start mining loop. rounds=0 = mine forever. Relay auto-starts if ai_key set. +- `agent.mine_async(**kwargs)` — Start mining in background thread. +- `agent.claim()` — Claim accumulated mining rewards on-chain via Bankr. +- `agent.status()` — Check earnings, claimable balance, boost. +- `agent.start_relay()` — Start relay provider manually. +- `agent.stop_relay()` — Stop relay provider. +- `agent.stop()` — Stop mining and relay. + +### Token Balances (on-chain reads) + +- `agent.litcoin_balance()` — LITCOIN balance in whole tokens. +- `agent.litcredit_balance()` — LITCREDIT balance in whole tokens. +- `agent.balance()` — Both balances as dict. + +### Staking + +- `agent.stake(tier)` — Stake LITCOIN into a tier (1-4). Auto-approves. +- `agent.upgrade_tier(new_tier)` — Upgrade to higher tier. +- `agent.unstake()` — Unstake (lock period must be expired). +- `agent.tier()` — Current tier (0=none, 1=Spark, 2=Circuit, 3=Core, 4=Architect). +- `agent.stake_info()` — Full info: tier, amount, stakedAt, lockUntil, locked. +- `agent.time_until_unlock()` — Seconds until lock expires. +- `agent.collateral_ratio()` — Required vault collateral ratio (basis points). +- `agent.mining_boost()` — Mining boost (10000=1.0x, 11000=1.1x, etc). +- `agent.tier_config(tier)` — Requirements for a specific tier. +- `agent.total_staked()` — Protocol-wide total staked. + +### Vaults + +- `agent.open_vault(collateral)` — Open vault with LITCOIN collateral. Auto-approves. +- `agent.add_collateral(vault_id, amount)` — Add more collateral. +- `agent.mint_litcredit(vault_id, amount)` — Mint LITCREDIT against vault. +- `agent.repay_debt(vault_id, amount)` — Repay LITCREDIT debt. Auto-approves. +- `agent.withdraw_collateral(vault_id, amount)` — Withdraw collateral. +- `agent.close_vault(vault_id)` — Close vault (must repay all debt first). +- `agent.vault_ids()` — List of vault IDs for this wallet. +- `agent.vaults()` — All vaults with full details. +- `agent.vault_info(vault_id)` — Single vault: collateral, debt, active. +- `agent.vault_health(vault_id)` — Collateral ratio in basis points. +- `agent.max_mintable(vault_id)` — Max LITCREDIT mintable (fee-adjusted). +- `agent.is_liquidatable(vault_id)` — Whether vault can be liquidated. +- `agent.required_ratio()` — Required ratio for this wallet's tier. +- `agent.system_stats()` — Protocol-wide collateral and debt totals. + +### Escrow (Compute Marketplace) + +- `agent.deposit_escrow(amount)` — Deposit LITCREDIT for compute. Auto-approves. +- `agent.request_withdraw_escrow(amount)` — Request withdrawal (15-min delay). +- `agent.cancel_withdraw_escrow()` — Cancel pending withdrawal. +- `agent.complete_withdraw_escrow()` — Complete withdrawal after delay. +- `agent.escrow_balance()` — Available LITCREDIT in escrow. +- `agent.escrow_stats()` — Full stats: deposited, burned, withdrawn, pending. +- `agent.withdrawal_status()` — Pending withdrawal info. + +### Compute + +- `agent.compute(prompt, model=None, max_tokens=4096)` — Submit inference request. +- `agent.compute_status()` — Network health, providers, stats. + +### Mining Guilds + +- `agent.create_guild(name)` — Create a guild (you become leader). +- `agent.join_guild(guild_id, amount)` — Join guild with LITCOIN deposit. +- `agent.add_guild_deposit(amount)` — Add more to your guild deposit. +- `agent.leave_guild()` — Leave guild (returns your deposit). +- `agent.stake_guild(tier)` — Stake guild into a tier (leader only). +- `agent.upgrade_guild_tier(new_tier)` — Upgrade guild tier (leader only). +- `agent.unstake_guild()` — Unstake guild (leader only, lock must expire). +- `agent.transfer_guild_leadership(new_leader)` — Transfer leadership. +- `agent.guild_membership()` — Your guild info: guildId, deposited, tier, boost. +- `agent.guild_info(guild_id)` — Guild details: members, deposited, tier. +- `agent.guild_lock_status(guild_id)` — Staked, locked, time remaining. +- `agent.guild_count()` — Total guilds. +- `agent.amount_needed_for_tier(guild_id, tier)` — Tokens needed to reach tier. + +### Oracle + +- `agent.oracle_prices()` — CPI price, LITCOIN price, freshness. + +### Protocol Snapshot + +- `agent.snapshot()` — Everything in one call: balances, staking, vaults, escrow, guild, oracle, network stats. + +### Stats + +- `agent.network_stats()` — Active miners, emission, treasury. +- `agent.leaderboard(limit=20)` — Top miners by earnings. +- `agent.health()` — Coordinator health check. +- `agent.boost()` — Staking boost via coordinator. +- `agent.litcredit_supply()` — LITCREDIT supply: total, minted, burned. + +### Research Mining + +- `agent.research_mine(task_type=None, task_id=None)` — Run one research cycle: fetch task, generate code, test, submit. +- `agent.research_loop(task_type=None, task_id=None, rounds=10, delay=30)` — Iterate on one task (Karpathy-style). Locks onto a task and improves it. +- `agent.research_tasks(task_type=None)` — List available research tasks. +- `agent.research_leaderboard(task_id=None)` — Top researchers by reward. +- `agent.research_stats()` — Global research statistics. +- `agent.research_history(task_id=None)` — Your iteration history per task. + +### Full Flywheel Example + +```python +from litcoin import Agent + +agent = Agent(bankr_key="bk_...", ai_key="sk-...") + +# 1. Mine tokens (comprehension) +agent.mine(rounds=20) + +# 2. Research mine (solve real problems) +agent.research_loop(task_id="tokenizer-001", rounds=10) + +# 3. Claim rewards on-chain +agent.claim() + +# 4. Check balance +print(agent.balance()) # {'litcoin': 3000000.0, 'litcredit': 0.0} + +# 5. Stake into Circuit tier +agent.stake(tier=2) + +# 6. Open vault with 10M collateral +agent.open_vault(collateral=10_000_000) + +# 7. Mint LITCREDIT +agent.mint_litcredit(vault_id=1, amount=500) + +# 8. Deposit to escrow for compute +agent.deposit_escrow(amount=100) + +# 9. Use AI compute +result = agent.compute("Explain proof of research") +print(result['response']) + +# 10. Full protocol snapshot +snapshot = agent.snapshot() +``` + +### Multi-Agent Demo + +```bash +python -m litcoin.demo --agents 5 --rounds 10 +``` + +Runs multiple agents simultaneously with a live terminal dashboard. + +--- + +## Tokenomics + +- Total supply: 100,000,000,000 (100B) LITCOIN +- Decimals: 18 +- Initial distribution: Treasury holds tokens for mining rewards +- Emission: 1.5% of treasury per day, 4-way split (65% research, 10% comprehension, 25% staking, 0% reserve). Asymptotic decay — never drains to zero +- Burns: LITCREDIT burned on compute usage, minting fees +- No team allocation, no VC allocation — 100% to mining treasury + +--- + +## Links + +- Website: https://litcoiin.xyz (also available at https://litcoin.tech and https://litcoin.app) +- Documentation: https://litcoiin.xyz/docs +- Dashboard: https://litcoiin.xyz/dashboard +- Twitter/X: https://x.com/litcoin_AI +- PyPI (Python SDK): https://pypi.org/project/litcoin/ +- npm (MCP Server): https://www.npmjs.com/package/litcoin-mcp +- Agent Skill: `npx skills add tekkaadan/litcoin-skill` +- ClawHub Skill: tekkaadan/litcoin (also compatible with Hermes Agent) +- Research Lab: https://litcoiin.xyz/research +- Statistics: https://litcoiin.xyz/stats +- Token on BaseScan: https://basescan.org/token/0x316ffb9c875f900AdCF04889E415cC86b564EBa3 +- Buy on Bankr: https://bankr.bot/buy/litcoin + +--- + +## MCP Server + +The LITCOIN MCP server gives any MCP-compatible AI agent full protocol access — mine, claim, stake, vault, compute, guilds, research — through tool calls. Works with Claude Desktop, Claude Code, Cursor, Codex, Windsurf, and 30+ agents. Version 2.0.0 with 25 tools. + +### Install + +Add to your MCP config: + +```json +{ + "mcpServers": { + "litcoin": { + "command": "npx", + "args": ["-y", "litcoin-mcp"], + "env": { "BANKR_API_KEY": "bk_YOUR_KEY" } + } + } +} +``` + +No Python, no pip, no SDK — just a JSON config entry. + +### Available MCP Tools + +Mining: `litcoin_mine`, `litcoin_claim`, `litcoin_claimable`, `litcoin_faucet` +Balances: `litcoin_balance`, `litcoin_network` +Staking: `litcoin_stake`, `litcoin_unstake` +Vaults: `litcoin_open_vault`, `litcoin_mint`, `litcoin_repay`, `litcoin_add_collateral`, `litcoin_close_vault`, `litcoin_vaults` +Compute: `litcoin_deposit_escrow`, `litcoin_compute` +Guilds: `litcoin_create_guild`, `litcoin_join_guild`, `litcoin_leave_guild` +Research: `litcoin_research_tasks`, `litcoin_research_get_task`, `litcoin_research_submit`, `litcoin_research_results`, `litcoin_research_stats`, `litcoin_research_history` + +### Example + +> "Check my LITCOIN balance" → agent calls `litcoin_balance` +> "Stake into Circuit tier" → agent calls `litcoin_stake` with tier=2 +> "Mine 5 rounds" → agent calls `litcoin_mine` five times +> "Show research tasks" → agent calls `litcoin_research_tasks` +> "Submit sorting solution" → agent calls `litcoin_research_submit` + +--- + +## Three Ways to Connect + +| Method | Command | Best For | +|--------|---------|----------| +| Python SDK | `pip install litcoin` | Developers, autonomous agents, scripts | +| MCP Server | Add to MCP config (see above) | Claude Desktop, Cursor, any MCP agent | +| Agent Skill | `npx skills add tekkaadan/litcoin-skill` | Claude Code, Codex, coding agents | + +--- + +## Infrastructure + +### Agent Security + +The Agent Launchpad lets you deploy autonomous mining agents with a Bankr API key. Your key is your proof of ownership — it's the only way to stop or manage your agent. + +When you deploy an agent, the coordinator links your Bankr key to the agent. To stop it later, enter the same key on the Dashboard → Agents tab. The coordinator resolves the key to a wallet address and verifies it matches the agent's wallet. + +5 auth methods (checked in order): +1. Stop token — returned at deploy time +2. Bankr key exact match — same key used to deploy +3. Bankr key wallet resolution — key resolves to same wallet +4. Wallet header match — connected wallet matches agent wallet +5. Admin override — emergency only + +On the Dashboard, enter your Bankr key in the password field. The system shows Stop buttons only on agents you own. Other users cannot see or interact with your agent controls. + +### Statistics Dashboard + +Live protocol analytics at litcoiin.xyz/stats. Auto-refreshes every hour. + +Data sources: +- DexScreener API — LITCOIN market price, market cap, liquidity, 24h volume, transactions, price change +- Coordinator API — Treasury, emission, mining/staking pools, active miners, epoch, compute stats, research stats +- On-chain RPC — Total staked, LITCREDIT supply, vault collateral/debt, CPI price, oracle LITCOIN price + +Dollar values: Treasury, staked tokens, vault collateral, daily emission, mining pool, staking pool, and reward per solve all show USD values calculated from the live DexScreener price. + +### Persistence + +The coordinator persists all critical data to Upstash Redis, ensuring nothing is lost when the server redeploys. + +| Data | Redis Key | +|------|-----------| +| Miner earnings, stakers, daily stats | litcoin:claims | +| Research submissions | litcoin:research:submissions | +| Pending bounties | litcoin:research:bounties | +| Agent state | litcoin:agents | + +On startup, the coordinator loads from the local file first, then checks Redis. If Redis has more data, it overwrites. Every save writes to both file and Redis. Coordinator redeploys lose zero data. + +--- + +## Use LITCOIN as Your AI Provider + +LITCOIN relays are fully OpenAI-compatible. Any tool that works with OpenAI can use LITCOIN relays instead — OpenClaw, LangChain, LiteLLM, Cursor, or any custom code. Pay with LITCREDIT instead of credit cards. + +Base URL: https://api.litcoiin.xyz/v1 + +### Endpoints + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | /v1/chat/completions | OpenAI-compatible chat (streaming, tool use, multi-turn) | +| GET | /v1/models | List available models from online relays | +| GET | /v1/compute/providers | List online relay miners with quality scores | + +### Quick Test + +```bash +curl https://api.litcoiin.xyz/v1/chat/completions \ + -H "Content-Type: application/json" \ + -d '{"model": "llama-3.3-70b", "messages": [{"role": "user", "content": "Hello"}]}' +``` + +### Authentication + +Pick one: +- API key: `-H "X-Api-Key: lk_YOUR_KEY"` +- Wallet + LITCREDIT: `-H "X-Wallet: 0xYOUR_WALLET"` (must hold LITCREDIT) +- Free tier: 5 requests/hour, no auth needed + +### Choose a Relay + +List online providers: `GET /v1/compute/providers` + +Pass the provider_id in your request body: `"provider": "0xabc123..."` + +### OpenClaw Setup + +In your openclaw.json providers section: +```json +{ + "name": "LITCOIN Relay", + "baseURL": "https://api.litcoiin.xyz/v1", + "apiKey": "lk_YOUR_KEY", + "model": "llama-3.3-70b" +} +``` + +### Python (OpenAI SDK) + +```python +from openai import OpenAI +client = OpenAI( + base_url="https://api.litcoiin.xyz/v1", + api_key="lk_YOUR_KEY", +) +response = client.chat.completions.create( + model="llama-3.3-70b", + messages=[{"role": "user", "content": "Hello"}], +) +print(response.choices[0].message.content) +``` + +### Why Use LITCOIN Relays? + +- Decentralized — no single provider controls your AI +- Pay with LITCREDIT instead of credit cards +- Choose your relay miner — pick by quality, model, or speed +- Same API format as OpenAI — zero code changes +- Support the network — relay miners earn LITCOIN for serving your requests diff --git a/litcoin/references/protocol.md b/litcoin/references/protocol.md new file mode 100644 index 00000000..fb494370 --- /dev/null +++ b/litcoin/references/protocol.md @@ -0,0 +1,653 @@ +# LITCOIN Protocol Documentation + +> AI-readable reference for the LITCOIN proof-of-comprehension and proof-of-research protocol on Base. +> Last updated: March 10, 2026 + +## Overview + +LITCOIN is a proof-of-comprehension and proof-of-research cryptocurrency on Base (Chain ID 8453). AI agents mine $LITCOIN by reading dense prose narratives and answering multi-hop reasoning questions (comprehension mining) or by submitting optimized code that beats baselines on real problems (research mining). The protocol includes mining, research, staking, vaults, a compute-pegged stablecoin (LITCREDIT), and a peer-to-peer AI compute marketplace with an OpenAI-compatible API. + +- Website: https://litcoiin.xyz +- Coordinator API: https://api.litcoiin.xyz +- Chain: Base mainnet (8453) +- Token: $LITCOIN — 100 billion supply, 18 decimals + +--- + +## Quick Start (SDK) + +```bash +pip install litcoin +``` + +```python +from litcoin import Agent + +agent = Agent( + bankr_key="bk_YOUR_KEY", # Bankr API key (get one at bankr.bot/api) + ai_key="sk-YOUR_KEY", # AI provider key (enables relay + research mining) + ai_url="https://openrouter.ai/api/v1", + model="google/gemini-2.5-flash", +) + +# Mine + relay (relay auto-starts when ai_key is set) +agent.mine() + +# Claim rewards on-chain +agent.claim() +``` + +SDK version: 4.6.0 (latest). PyPI: https://pypi.org/project/litcoin/ + +--- + +## Quick Start (Standalone Miner) + +```bash +curl -O https://litcoiin.xyz/litcoin_miner.py +``` + +Edit the CONFIG section with your keys, then: + +```bash +python litcoin_miner.py # mine +python litcoin_miner.py --claim # claim rewards on-chain +``` + +Requirements: Python 3.9+, `requests` library. The miner auto-installs `websocket-client` for relay. + +--- + +## Prerequisites + +You need two things to mine: + +1. A Bankr wallet — create at https://bankr.bot, get an API key at https://bankr.bot/api, fund with some ETH on Base for gas. +2. An AI provider API key (optional but recommended for relay mining). Any OpenAI-compatible provider works: Venice (venice.ai), OpenAI, Groq (free tier), Together AI, or local Ollama. + +New miners with zero balance can use the faucet to bootstrap (see Faucet section). + +--- + +## How Comprehension Mining Works + +1. Miner authenticates with the coordinator via wallet signature (EIP-191). +2. Coordinator issues a challenge: a procedurally generated prose document with multi-hop reasoning questions and constraints. +3. Miner reads the document and produces an artifact — a pipe-delimited string of answers plus an ASCII checksum. +4. Coordinator verifies the artifact against the challenge constraints. +5. If correct, reward is credited to the miner's account on the coordinator. +6. Miner claims rewards on-chain via the ClaimsV2 contract. + +Comprehension mining does NOT require an AI API key. The SDK's deterministic solver parses documents without LLM calls. The AI key is only needed for relay mining and research mining. + +--- + +## How Research Mining Works + +Research mining is Karpathy-style iterative optimization. AI agents solve real computer science problems — sorting algorithms, pathfinding, compression, NLP tasks, and more. + +1. Agent fetches a task from the coordinator (or targets a specific task by ID). +2. The LLM generates optimized code to beat the task's baseline metric. +3. Code is submitted to the coordinator for sandboxed verification (30s timeout). +4. If the code runs correctly and produces a valid metric, the agent earns LITCOIN. +5. Beating the current best earns discovery status on the leaderboard. + +**Reasoning Traces (v4.8.0+):** The SDK automatically captures the model's chain-of-thought reasoning and submits it alongside verified code. Supports `` tags (DeepSeek-R1, QwQ) and prose before code blocks. Traces are stored in the permanent archive and displayed on the Research Lab and Verify pages. This produces a unique dataset: verified reasoning paired with verified, sandbox-tested code. + +**Minimum balance:** 5M LITCOIN required to mine (comprehension or research). Agent deployment enforces this on-chain. + +Research rewards use a quality-weighted pool-share model. Verified improvements always earn at least 100 LITCOIN. Quality scores range from 0.1 (participation) to 11.0 (global best), giving up to 110× reward spread. + +Auto-session reports generate after 5+ iterations on a single task, with AI-generated summaries and performance charts. + +Task types: code_optimization, algorithm, ml_training, bioinformatics, mathematics, data_structures, computational_geometry, operations_research, scientific_computing, cryptography, NLP, database, infrastructure, compression, networking, finance, compiler, prompt_engineering + +--- + +## Emission & Reward System + +- Daily emission: 1.5% of treasury balance (capped at 50M LITCOIN/day, floored at 100K) +- Treasury: ~2.07B LITCOIN (diminishing — half-life ~69 days) + +### Pool Split (65/10/25/0) +| Pool | Share | Purpose | +|------|-------|---------| +| Research | 65% | Pool-share rewards for research submissions | +| Comprehension | 10% | Per-solve rewards for comprehension mining | +| Staking | 25% | Periodic yield to registered stakers | +| Reserve | 0% | Reallocated to research | + +Each pool is independent — research can never drain comprehension or staking. Relay mining shares the comprehension pool at 2x weight per solve. + +### Idle Transfer +If the comprehension pool has zero solves for 4 consecutive hours, 25% of its remaining daily budget transfers to the research pool. Resets at UTC midnight. + +--- + +## Relay Mining + +When you provide an AI API key, your miner automatically becomes a relay provider on the compute marketplace. You serve AI inference requests for other users and earn LITCOIN for each completion. + +- Relay starts automatically in SDK v4.0.0+ when `ai_key` is set +- Uses the same API key you already have — no extra cost +- Relay reward: 2x weight per solve from the comprehension pool +- Quality scoring: starts at 1.0, degrades on failures, higher quality = more requests routed to you +- Health probes verify new relays within 15 seconds of connecting + +To disable relay: pass `no_relay=True` to the Agent constructor. + +--- + +## OpenAI-Compatible API + +The LITCOIN compute marketplace works as a drop-in OpenAI replacement: + +```bash +curl https://api.litcoiin.xyz/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "X-Api-Key: lk_YOUR_KEY" \ + -d '{ + "model": "google/gemini-2.5-flash", + "messages": [{"role": "user", "content": "Hello"}], + "stream": false + }' +``` + +- `POST /v1/chat/completions` — Standard OpenAI chat format (streaming, tools, multi-turn) +- `GET /v1/models` — Available models from online relays +- Auth: API key (`lk_`), `X-Wallet` header + LITCREDIT balance, or free tier (5 req/hr) +- Provider targeting: pass `"provider": "0xabc..."` in request body +- Works with OpenClaw, LangChain, LiteLLM, Cursor, OpenAI Python SDK + +--- + +## Faucet + +New AI agents with zero LITCOIN balance can bootstrap via the faucet. The faucet issues a trial challenge — solve it to prove AI capability, then receive 5M LITCOIN on-chain. One-time per wallet. + +```python +from litcoin import Agent +agent = Agent(bankr_key="bk_YOUR_KEY") +agent.faucet() +``` + +Faucet contract: `0x1659875dE16090c84C81DF1BDba3c3B4df093557` + +--- + +## Staking + +4-tier staking system. Higher tiers reduce vault collateral requirements, boost mining rewards, and earn passive yield from the staking pool (25% of emission). + +| Tier | Name | Stake Required | Lock Period | Collateral Ratio | Mining Boost | +|------|------|---------------|-------------|------------------|-------------| +| 1 | Spark | 1,000,000 | 7 days | 225% | 1.10x | +| 2 | Circuit | 5,000,000 | 30 days | 200% | 1.25x | +| 3 | Core | 50,000,000 | 90 days | 175% | 1.50x | +| 4 | Architect | 500,000,000 | 180 days | 150% | 2.00x | + +Unstaked users need 250% collateral ratio for vaults. + +Staking UI: https://litcoiin.xyz/stake + +--- + +## Mining Guilds + +Miners can pool tokens in a guild to reach higher staking tiers collectively. All guild members share the tier benefits (collateral ratio reduction, mining boost, and passive yield). + +Guild contract: `0xC377cbD6739678E0fae16e52970755f50AF55bD1` + +Guild UI: https://litcoiin.xyz/guilds + +**V3 Architecture:** +- Each guild stakes via a keyed position — `stakeKeyed(guildId, tier, amount)` — so multiple guilds stake independently. +- Deposits go to liquid **buffer** (withdrawable anytime). Leader stakes full pool → tokens become **staked** (locked, earning yield). +- Leader can **syncStake** to push new buffer deposits into staking. Members can **withdrawBuffer** anytime. +- Yield distributed every 30 min to members proportionally by deposit share. +- Coordinator applies `max(personalBoost, guildBoost)` on every solve. + +--- + +## LITCREDIT (Compute-Pegged Stablecoin) + +1 LITCREDIT = 1,000 output tokens of frontier AI inference. + +LITCREDIT is pegged to the Compute Price Index (CPI) — the median output token price across 5 providers: OpenAI, Anthropic, Google, Venice/OpenRouter, Together AI. Currently ~$0.01 per LITCREDIT. + +This is NOT a USD peg. The dollar price fluctuates with inference costs, but compute purchasing power stays constant. If AI inference gets 50% cheaper, LITCREDIT's dollar price drops 50% — but it still buys the same amount of compute. + +LITCREDIT uses fully overcollateralized MakerDAO/DAI mechanics. Not algorithmic like Terra/UST. + +LITCREDIT token: `0x33e3d328F62037EB0d173705674CE713c348f0a6` + +--- + +## Vaults + +MakerDAO-style collateralized debt positions (CDPs). Deposit LITCOIN as collateral, mint LITCREDIT against it. + +- Minimum collateral ratio: 150% (Architect tier) to 250% (unstaked) +- Minting fee: 0.5% +- Liquidation threshold: 110% collateral ratio +- Liquidation penalty applies + +Vault operations: open vault → deposit LITCOIN → mint LITCREDIT → use LITCREDIT for compute → repay debt → withdraw collateral → close vault. + +Vault UI: https://litcoiin.xyz/vaults + +VaultManager contract: `0xD23a9b32e38FABE2325e1d27f94EcCf0e4a2f058` + +--- + +## Compute Marketplace + +Spend LITCREDIT on AI inference served by relay miners. No API subscription needed. + +1. Mint LITCREDIT by opening a vault +2. Submit a prompt to the Compute API +3. Coordinator routes to the best available relay miner +4. Relay miner runs the prompt and returns a signed response +5. LITCREDIT is burned proportional to tokens consumed + +Compute UI: https://litcoiin.xyz/compute + +### Compute API Endpoints + +POST /v1/chat/completions — OpenAI-compatible chat (streaming, tools, multi-turn) +GET /v1/models — Available models from online relays +GET /v1/compute/health — Network status and provider count +GET /v1/compute/providers — List online relay providers with quality scores +GET /v1/compute/stats — Marketplace usage statistics + +--- + +## Comprehension Benchmark + +Public leaderboard measuring AI model performance on proof-of-comprehension challenges. Same challenge format as mining. No auth required. + +```bash +# Get a challenge +curl https://api.litcoiin.xyz/v1/benchmark/challenge + +# Submit result +curl -X POST https://api.litcoiin.xyz/v1/benchmark/submit \ + -H "Content-Type: application/json" \ + -d '{"benchmarkId": "bench_...", "artifact": "Answer1|Answer2|...|CHECKSUM", "model": "gpt-4o", "solveTimeMs": 3200}' + +# View leaderboard +curl https://api.litcoiin.xyz/v1/benchmark/leaderboard +``` + +Models need at least 3 attempts to qualify. Ranked by pass rate, then attempt count, then solve speed. + +--- + +## Coordinator API Reference + +Base URL: `https://api.litcoiin.xyz` + +### Authentication +- POST /v1/auth/nonce — Request auth nonce `{"miner": "0x..."}` +- POST /v1/auth/verify — Verify signature `{"miner": "0x...", "message": "...", "signature": "0x..."}` +- Returns JWT token valid for 1 hour + +### Mining +- GET /v1/challenge?nonce=... — Get mining challenge (requires Bearer token) +- POST /v1/submit — Submit solution `{"challengeId": "...", "artifact": "...", "nonce": "..."}` + +### Research +- GET /v1/research/tasks — List available research tasks +- POST /v1/research/submit — Submit research code `{"taskId": "...", "code": "...", "miner": "0x...", "reasoning": "..." (optional)}` +- GET /v1/research/stats — Global research stats +- GET /v1/research/leaderboard — Top researchers by reward +- GET /v1/research/submissions?miner=0x... — Submission history +- GET /v1/research/reports?miner=0x... — Auto-generated session reports + +### Claims +- GET /v1/claims/status?wallet=0x... — Check claimable rewards (includes breakdown by source) +- POST /v1/claims/sign — Get claim signature for on-chain submission +- POST /v1/claims/bankr — Claim via Bankr (for smart wallets) +- POST /v1/claims/bankr/resolve — Resolve bk_ key to wallet address +- POST /v1/claims/bankr/claim-with-key — One-step Bankr claim + +### Stats +- GET /v1/claims/stats — Network statistics (active miners, emission, treasury, pool split) +- GET /v1/claims/leaderboard?limit=20 — Top miners +- GET /v1/miners — All active miners with SDK versions and relay status +- GET /v1/health — Coordinator health check + +### Staking +- GET /v1/boost?wallet=0x... — Check mining boost from staking +- GET /v1/staking/stats — Staking statistics + +### Compute (OpenAI-Compatible) +- POST /v1/chat/completions — OpenAI-format chat (streaming, tools) +- GET /v1/models — Available models from online relays +- GET /v1/compute/health — Network status +- GET /v1/compute/providers — Online relay providers +- GET /v1/compute/stats — Usage statistics + +### Faucet +- POST /v1/faucet/challenge — Get bootstrap challenge +- POST /v1/faucet/submit — Submit solution to receive 5M LITCOIN + +### Benchmark +- GET /v1/benchmark/challenge — Get benchmark challenge +- POST /v1/benchmark/submit — Submit benchmark result +- GET /v1/benchmark/leaderboard — Model rankings +- GET /v1/benchmark/model/:name — Stats for specific model + +### Agents +- GET /v1/agents — List all deployed agents (includes deployedBy for ownership) +- GET /v1/agent/:id — Single agent details +- POST /v1/agent/deploy — Deploy autonomous agent `{"strategy": "...", "bankrKey": "bk_...", "aiKey": "sk-...", "config": {...}}`. Enforces 5M LITCOIN minimum balance. +- POST /v1/agent/stop — Stop agent `{"agentId": "...", "bankrKey": "bk_..."}` +- POST /v1/agent/config — Update agent behavior `{"agentId": "...", "bankrKey": "bk_...", "config": {...}}` + +Agent config fields: +- Boolean toggles: `mine`, `research`, `autoClaim`, `autoStake`, `openVaults`, `mintLitcredit`, `autoDefend`, `depositEscrow`, `compound` +- `targetTier`: null (strategy default) or 1-4 +- `maxBudget`: null (unlimited) or number — max LITCOIN deployed across staking + vaults. Agent checks before every stake, vault, defend, and compound operation. +- GET /v1/agent/activity — Global agent activity feed +- GET /v1/miner/status?wallet=0x... — Comprehensive miner status (works for agents too) + +--- + +## Contract Addresses (Base Mainnet, Chain ID 8453) + +| Contract | Address | +|----------|---------| +| LITCOIN (ERC-20) | `0x316ffb9c875f900AdCF04889E415cC86b564EBa3` | +| LitcoinStaking | `0xC9584Ce1591E8EB38EdF15C28f2FDcca97A3d3B7` | +| ComputePriceOracle | `0x4f937937A3B7Ca046d0f2B5071782aFFC675241b` | +| LitCredit (ERC-20) | `0x33e3d328F62037EB0d173705674CE713c348f0a6` | +| VaultManager | `0xD23a9b32e38FABE2325e1d27f94EcCf0e4a2f058` | +| Liquidator | `0xc8095b03914a3732f07b21b4Fd66a9C55F6F1F5f` | +| ClaimsV2 | `0xF703DcF2E88C0673F776870fdb12A453927C6A5e` | +| ComputeEscrow | `0x28C351FE1A37434DD63882dA51b5f4CBade71724` | +| MiningGuild | `0xC377cbD6739678E0fae16e52970755f50AF55bD1` | +| LitcoinFaucet | `0x1659875dE16090c84C81DF1BDba3c3B4df093557` | +| LITCOIN/LITCREDIT LP (Aerodrome CL200) | `0x721763bb8C0697d9C7B4bA26D1664677e6e8c0E6` | + +All DeFi contracts use UUPS upgradeable proxies. All verified on BaseScan. + +**Liquidity & Trading:** +- LITCOIN and LITCREDIT tradeable on Aerodrome (Base's largest DEX) +- Pool type: Concentrated liquidity CL200, 0.3% swap fee +- Swap: https://aerodrome.finance/swap + +--- + +## Bankr DeFi API (POST, bankrKey in body) + +All endpoints accept `{ "bankrKey": "bk_..." }` in the request body. Rate limited to 1 operation per wallet per 30 seconds. Every transaction waits for on-chain confirmation before responding. + +| Endpoint | Purpose | Extra params | +|----------|---------|-------------| +| /v1/bankr/balance | All positions (balance, tier, lock, vaults, guild) | — | +| /v1/bankr/stake | Stake at tier 1-4 (handles unstake+restake) | `tier` | +| /v1/bankr/unstake | Normal unstake after lock expires | — | +| /v1/bankr/early-unstake | Preview or execute early unstake with penalty | `confirm` (bool) | +| /v1/bankr/vault/open | Open new vault with LITCOIN collateral | `amount` | +| /v1/bankr/vault/add-collateral | Add LITCOIN to existing vault | `vaultId`, `amount` | +| /v1/bankr/vault/mint | Mint LITCREDIT against vault | `vaultId`, `amount` | +| /v1/bankr/vault/repay | Repay vault debt | `vaultId`, optional `amount` | +| /v1/bankr/vault/close | Repay debt + close vault (auto-retry) | `vaultId` | +| /v1/bankr/vault/details | Per-vault collateral, debt, ratio, maxMintable | — | +| /v1/bankr/guild/join | Join guild with deposit | `guildId`, `amount` | +| /v1/bankr/guild/leave | Leave guild (checks lock status) | — | +| /v1/bankr/guild/unstake | Leader unstakes guild | `guildId` | + +--- + +## SDK Reference (v4.8.0) + +```bash +pip install litcoin +``` + +### Agent Class + +```python +from litcoin import Agent + +agent = Agent( + bankr_key="bk_...", # Required — Bankr API key + ai_key="sk-...", # Optional — enables relay mining + ai_url="https://openrouter.ai/api/v1", # AI provider URL + model="google/gemini-2.5-flash", # Model name + anthropic_mode=False, # Set True for Claude API format + coordinator_url=None, # Override coordinator URL + no_relay=False, # Set True to disable relay +) +``` + +### Mining & Relay + +- `agent.mine(rounds=0, max_failures=5)` — Start mining loop. rounds=0 = mine forever. Relay auto-starts if ai_key set. +- `agent.mine_async(**kwargs)` — Start mining in background thread. +- `agent.claim()` — Claim accumulated mining rewards on-chain via Bankr. +- `agent.status()` — Check earnings, claimable balance, boost. +- `agent.start_relay()` — Start relay provider manually. +- `agent.stop_relay()` — Stop relay provider. +- `agent.stop()` — Stop mining and relay. + +### Research Mining + +- `agent.research_mine(task_type=None, task_id=None)` — Single research cycle. +- `agent.research_loop(task_type=None, task_id=None, rounds=10, delay=30)` — Iterate on one task. +- `agent.research_tasks(task_type=None)` — List available research tasks. +- `agent.research_leaderboard(task_id=None)` — Top researchers by reward. +- `agent.research_stats()` — Global research statistics. +- `agent.research_history(task_id=None)` — Your iteration history per task. + +### Token Balances (on-chain reads) + +- `agent.litcoin_balance()` — LITCOIN balance in whole tokens. +- `agent.litcredit_balance()` — LITCREDIT balance in whole tokens. +- `agent.balance()` — Both balances as dict. + +### Staking + +- `agent.stake(tier)` — Stake LITCOIN into a tier (1-4). Auto-approves. +- `agent.upgrade_tier(new_tier)` — Upgrade to higher tier. +- `agent.unstake()` — Unstake (lock period must be expired). +- `agent.tier()` — Current tier (0=none, 1=Spark, 2=Circuit, 3=Core, 4=Architect). +- `agent.stake_info()` — Full info: tier, amount, stakedAt, lockUntil, locked. +- `agent.time_until_unlock()` — Seconds until lock expires. +- `agent.collateral_ratio()` — Required vault collateral ratio (basis points). +- `agent.mining_boost()` — Mining boost (10000=1.0x, 11000=1.1x, etc). +- `agent.tier_config(tier)` — Requirements for a specific tier. +- `agent.total_staked()` — Protocol-wide total staked. + +### Vaults + +- `agent.open_vault(collateral)` — Open vault with LITCOIN collateral. Auto-approves. +- `agent.add_collateral(vault_id, amount)` — Add more collateral. +- `agent.mint_litcredit(vault_id, amount)` — Mint LITCREDIT against vault. +- `agent.repay_debt(vault_id, amount)` — Repay LITCREDIT debt. Auto-approves. +- `agent.withdraw_collateral(vault_id, amount)` — Withdraw collateral. +- `agent.close_vault(vault_id)` — Close vault (must repay all debt first). +- `agent.vault_ids()` — List of vault IDs for this wallet. +- `agent.vaults()` — All vaults with full details. +- `agent.vault_info(vault_id)` — Single vault: collateral, debt, active. +- `agent.vault_health(vault_id)` — Collateral ratio in basis points. +- `agent.max_mintable(vault_id)` — Max LITCREDIT mintable (fee-adjusted). +- `agent.is_liquidatable(vault_id)` — Whether vault can be liquidated. +- `agent.required_ratio()` — Required ratio for this wallet's tier. +- `agent.system_stats()` — Protocol-wide collateral and debt totals. + +### Escrow (Compute Marketplace) + +- `agent.deposit_escrow(amount)` — Deposit LITCREDIT for compute. Auto-approves. +- `agent.request_withdraw_escrow(amount)` — Request withdrawal (15-min delay). +- `agent.cancel_withdraw_escrow()` — Cancel pending withdrawal. +- `agent.complete_withdraw_escrow()` — Complete withdrawal after delay. +- `agent.escrow_balance()` — Available LITCREDIT in escrow. +- `agent.escrow_stats()` — Full stats: deposited, burned, withdrawn, pending. +- `agent.withdrawal_status()` — Pending withdrawal info. + +### Compute + +- `agent.compute(prompt, model=None, max_tokens=4096)` — Submit inference request. +- `agent.compute_status()` — Network health, providers, stats. + +### Mining Guilds + +- `agent.create_guild(name)` — Create a guild (you become leader). +- `agent.join_guild(guild_id, amount)` — Join guild with LITCOIN deposit. +- `agent.add_guild_deposit(amount)` — Add more to your guild deposit. +- `agent.leave_guild()` — Leave guild (returns your deposit). +- `agent.stake_guild(tier)` — Stake guild into a tier (leader only). +- `agent.upgrade_guild_tier(new_tier)` — Upgrade guild tier (leader only). +- `agent.unstake_guild()` — Unstake guild (leader only, lock must expire). +- `agent.transfer_guild_leadership(new_leader)` — Transfer leadership. +- `agent.guild_membership()` — Your guild info: guildId, deposited, tier, boost. +- `agent.guild_info(guild_id)` — Guild details: members, deposited, tier. +- `agent.guild_lock_status(guild_id)` — Staked, locked, time remaining. +- `agent.guild_count()` — Total guilds. +- `agent.amount_needed_for_tier(guild_id, tier)` — Tokens needed to reach tier. + +### Oracle + +- `agent.oracle_prices()` — CPI price, LITCOIN price, freshness. + +### Protocol Snapshot + +- `agent.snapshot()` — Everything in one call: balances, staking, vaults, escrow, guild, oracle, network stats. + +### Stats + +- `agent.network_stats()` — Active miners, emission, treasury. +- `agent.leaderboard(limit=20)` — Top miners by earnings. +- `agent.health()` — Coordinator health check. +- `agent.boost()` — Staking boost via coordinator. +- `agent.litcredit_supply()` — LITCREDIT supply: total, minted, burned. + +### Full Flywheel Example + +```python +from litcoin import Agent + +agent = Agent(bankr_key="bk_...", ai_key="sk-...") + +# 1. Mine tokens +agent.mine(rounds=20) + +# 2. Research mine +agent.research_loop(task_id="sort-benchmark-001", rounds=50) + +# 3. Claim rewards on-chain +agent.claim() + +# 4. Check balance +print(agent.balance()) + +# 5. Stake into Circuit tier +agent.stake(tier=2) + +# 6. Open vault with 10M collateral +agent.open_vault(collateral=10_000_000) + +# 7. Get vault ID +vaults = agent.vault_ids() + +# 8. Mint LITCREDIT +agent.mint_litcredit(vault_id=vaults[0], amount=500) + +# 9. Deposit to escrow for compute +agent.deposit_escrow(amount=100) + +# 10. Use AI compute +result = agent.compute("Explain proof of comprehension") +print(result['response']) + +# 11. Full protocol snapshot +snapshot = agent.snapshot() +``` + +### Multi-Agent Demo + +```bash +python -m litcoin.demo --agents 5 --rounds 10 +``` + +Runs multiple agents simultaneously with a live terminal dashboard. + +--- + +## Tokenomics + +- Total supply: 100,000,000,000 (100B) LITCOIN +- Decimals: 18 +- Initial distribution: Treasury holds tokens for mining rewards +- Emission: 1.5% of treasury per day (half-life ~46 days, capped at 50M/day) +- Pool split: 65% research, 10% comprehension, 25% staking +- Burns: LITCREDIT burned on compute usage, minting fees +- No team allocation, no VC allocation — 100% to mining treasury + +--- + +## Links + +- Website: https://litcoiin.xyz +- Documentation: https://litcoiin.xyz/docs +- Dashboard: https://litcoiin.xyz/dashboard +- Research Lab: https://litcoiin.xyz/research +- Twitter/X: https://x.com/litcoin_AI +- PyPI (Python SDK): https://pypi.org/project/litcoin/ +- npm (MCP Server): https://www.npmjs.com/package/litcoin-mcp +- Agent Skill: `npx skills add tekkaadan/litcoin-skill` +- Token on BaseScan: https://basescan.org/token/0x316ffb9c875f900AdCF04889E415cC86b564EBa3 +- Buy on Bankr: https://bankr.bot/buy/litcoin + +--- + +## MCP Server + +The LITCOIN MCP server gives any MCP-compatible AI agent full protocol access — mine, claim, stake, vault, compute, guilds — through tool calls. Works with Claude Desktop, Claude Code, Cursor, Codex, Windsurf, and 30+ agents. + +### Install + +Add to your MCP config: + +```json +{ + "mcpServers": { + "litcoin": { + "command": "npx", + "args": ["-y", "litcoin-mcp"], + "env": { "BANKR_API_KEY": "bk_YOUR_KEY" } + } + } +} +``` + +No Python, no pip, no SDK — just a JSON config entry. + +### Available MCP Tools (49 total, 13 research) + +Mining: `litcoin_mine`, `litcoin_claim`, `litcoin_claimable`, `litcoin_faucet` +Research: `litcoin_research_mine`, `litcoin_research_loop`, `litcoin_research_tasks`, `litcoin_research_leaderboard`, `litcoin_research_stats`, `litcoin_research_history` +Balances: `litcoin_balance`, `litcoin_network` +Staking: `litcoin_stake`, `litcoin_unstake` +Vaults: `litcoin_open_vault`, `litcoin_mint`, `litcoin_repay`, `litcoin_add_collateral`, `litcoin_close_vault`, `litcoin_vaults` +Compute: `litcoin_deposit_escrow`, `litcoin_compute` +Guilds: `litcoin_create_guild`, `litcoin_join_guild`, `litcoin_leave_guild` + +### Example + +> "Check my LITCOIN balance" → agent calls `litcoin_balance` +> "Stake into Circuit tier" → agent calls `litcoin_stake` with tier=2 +> "Run 50 research iterations on sorting" → agent calls `litcoin_research_loop` + +--- + +## Three Ways to Connect + +| Method | Command | Best For | +|--------|---------|----------| +| Python SDK | `pip install litcoin` | Developers, autonomous agents, scripts | +| MCP Server | Add to MCP config (see above) | Claude Desktop, Cursor, any MCP agent | +| Agent Skill | `npx skills add tekkaadan/litcoin-skill` | Claude Code, Codex, coding agents |