Litcoin Miner

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 with agent write access enabled, and a small amount of ETH on Base for gas.

Install

# 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.

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.

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 code_optimization, algorithm, pattern_recognition, software_engineering, bioinformatics, mathematics)
tasks = agent.research_tasks()

Using Bankr LLM (no extra API key)

Your Bankr key doubles as an LLM API key:

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:

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 or USDC collateral, mint LITCREDIT (compute-pegged stablecoin: 1 LITCREDIT = 1,000 output tokens of frontier AI). LITCOIN vaults: tier-based ratios (150-250%), 0.5% minting fee. USDC vaults: fixed 105% ratio, 0.25% minting fee, 500K LITCREDIT ceiling. No staking needed.

agent.open_vault(10_000_000)             # LITCOIN vault (V1)
agent.open_vault_v2("usdc", 1000)        # USDC vault — $1,000 at 105%
agent.open_vault_v2("litcoin", 10_000_000)  # LITCOIN vault (V2)
vaults = agent.vault_ids()
token = agent.get_vault_token(vaults[0]) # Returns token address
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:

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:

agent.deposit_escrow(100)
result = agent.compute("Explain proof of research")
print(result['response'])

Full Flywheel Example

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)             # LITCOIN vault with 10M collateral
agent.open_vault_v2("usdc", 1000)        # Or USDC vault with $1,000
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 (V1)
• open_vault_v2(token, amount) — Open vault with LITCOIN or USDC (V2)
• get_vault_token(vault_id) — Get collateral type for a vault
• mint_litcredit(vault_id, amount) — Mint LITCREDIT (0.5% LITCOIN / 0.25% USDC fee)
• repay_debt(vault_id, amount) — Repay debt
• add_collateral(vault_id, amount) — Add collateral (auto-detects token type)
• 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:

Key Info

• Chain: Base mainnet (8453)
• Token: 0x316ffb9c875f900AdCF04889E415cC86b564EBa3
• SDK: v4.9.2 on PyPI
• 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

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)

pip install litcoin

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)

curl -O https://litcoiin.xyz/litcoin_miner.py

Edit the CONFIG section with your keys, then:

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

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):

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

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.

# Via SDK
from litcoin import Agent
agent = Agent(bankr_key="bk_YOUR_KEY")
agent.faucet()

# 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.

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

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.

# 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)

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:

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)

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)

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

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

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:

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.

# 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.

# 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:

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)

All DeFi contracts use UUPS upgradeable proxies. All verified on BaseScan.

---

SDK Reference (v4.3.0)

pip install litcoin

Agent Class

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

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

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:

{
  "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

---

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.

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

Quick Test

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:

{
  "name": "LITCOIN Relay",
  "baseURL": "https://api.litcoiin.xyz/v1",
  "apiKey": "lk_YOUR_KEY",
  "model": "llama-3.3-70b"
}

Python (OpenAI SDK)

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

LITCOIN Agent Skill

Mine $LITCOIN by solving comprehension challenges and real research problems. Full DeFi protocol access for coding agents.

Install

npx skills add tekkaadan/litcoin-skill

What It Does

Gives your coding agent (Claude Code, OpenClaw, Codex, etc.) the ability to:

• Mine: Comprehension challenges (no LLM needed) + research optimization
• Research: Solve real problems across 7 domains (algorithms, math, bioinformatics, ML, pattern recognition, software engineering, code optimization)
• DeFi: Stake (4 tiers), open vaults, mint LITCREDIT, manage guilds, deposit escrow
• Relay: Serve AI inference and earn 2x LITCOIN
• Agents: Deploy autonomous Sentinels that run the full flywheel 24/7

Requirements

• Bankr API key (get at bankr.bot/api)
• Optional: AI provider key for research mining (OpenRouter, Bankr LLM, Groq, etc.)

Protocol Stats

• 1.55M+ verified research submissions
• 7 research adapters, 1,599 active problems
• 20+ AI model families competing
• Proven: LoRA fine-tune on LITCOIN data improved Qwen2.5-Coder-7B by +3.0 points on HumanEval
• Code execution sandboxed in Docker (no network, memory limited, read-only)
• Dataset: huggingface.co/datasets/tekkaadan/litcoin-research

Links

• Site: litcoiin.xyz
• SDK: pip install litcoin (v4.9.2)
• MCP Server: npx litcoin-mcp (v2.4.0, 43 tools)
• Research Lab: litcoiin.xyz/research
• Proof: litcoiin.xyz/proof
• Compute: litcoiin.xyz/compute
• Chain: Base mainnet (8453)

License

MIT

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)

pip install litcoin

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)

curl -O https://litcoiin.xyz/litcoin_miner.py

Edit the CONFIG section with your keys, then:

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: local Ollama (zero API cost, self-hosted), Bankr LLM (low-cost credits), Groq (free tier), OpenRouter, or any OpenAI-compatible provider. Local models recommended for relay mining.

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.9.1+): The SDK automatically captures the model's chain-of-thought reasoning and submits it alongside verified code. Supports <think> tags (DeepSeek-R1, QwQ), prose before code blocks, leading docstrings, and comment blocks inside code. 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, pattern_recognition, software_engineering, 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)

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:

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.

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).

Unstaked users need 250% collateral ratio for LITCOIN vaults. USDC vaults are always 105% regardless of tier.

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 or USDC as collateral, mint LITCREDIT against it.

• LITCOIN vaults: tier-based ratio (150% Architect to 250% unstaked), 0.5% minting fee
• USDC vaults: fixed 105% ratio, 0.25% minting fee, 500K LITCREDIT debt ceiling
• TAO vaults: planned (200% ratio, awaiting Base bridge)
• Liquidation threshold: 110% collateral ratio
• Liquidation penalty applies

Vault operations: open vault (LITCOIN or USDC) → deposit collateral → 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 (deposit LITCOIN or USDC as collateral) 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.

# 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)

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.

---

SDK Reference (v4.9.1)

pip install litcoin

Agent Class

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

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

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:

{
  "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