From bc040597649fc65d48ad9d28cacd8d1dc8ff69d6 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Sun, 8 Mar 2026 00:57:53 -0500 Subject: [PATCH 01/25] Create SKILL.md --- litcoin/SKILL.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 litcoin/SKILL.md diff --git a/litcoin/SKILL.md b/litcoin/SKILL.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/litcoin/SKILL.md @@ -0,0 +1 @@ + From 6c22030ebd3964ee9b1fc55533cb36aa4ffbbe30 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Sun, 8 Mar 2026 00:58:04 -0500 Subject: [PATCH 02/25] Add files via upload --- litcoin/SKILL.md | 111 +++++++++ litcoin/protocol.md | 549 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 660 insertions(+) create mode 100644 litcoin/protocol.md diff --git a/litcoin/SKILL.md b/litcoin/SKILL.md index 8b137891..71f29a0d 100644 --- a/litcoin/SKILL.md +++ b/litcoin/SKILL.md @@ -1 +1,112 @@ +--- +name: litcoin-miner +description: "Mine LITCOIN — a proof-of-comprehension cryptocurrency on Base. Use when the user wants to mine crypto with AI, earn tokens through reading comprehension, stake LITCOIN, open vaults, mint LITCREDIT (compute-pegged stablecoin), manage mining guilds, deposit to compute escrow, or interact with the LITCOIN DeFi protocol. Also use when the user asks about proof-of-comprehension mining, AI agent DeFi, or compute-pegged stablecoins." +--- +# LITCOIN Miner Skill + +Mine $LITCOIN by solving reading comprehension challenges on Base. Full DeFi protocol access: mine, claim, stake, vault, mint LITCREDIT, compute, guilds. + +## Install the SDK + +```bash +pip install litcoin +``` + +## Quick Start + +```python +from litcoin import Agent + +agent = Agent( + bankr_key="bk_YOUR_KEY", # Required — get at bankr.bot/api + ai_key="sk-YOUR_KEY", # Optional — enables relay mining (+33% rewards) + ai_url="https://api.venice.ai/api/v1", + model="llama-3.3-70b", +) + +# Mine (relay auto-starts if ai_key set) +agent.mine(rounds=10) + +# Claim rewards on-chain +agent.claim() +``` + +The user needs a Bankr API key from https://bankr.bot/api and some ETH on Base for gas. New wallets with zero balance can use the faucet: `agent.faucet()` gives 5M LITCOIN free (one-time). + +## What This Skill Covers + +When the user asks to mine LITCOIN, walk them through setup: + +1. **Install**: `pip install litcoin` +2. **Get keys**: Bankr API key from bankr.bot/api. Optionally an AI provider key (Venice, OpenAI, Groq) for relay mining. +3. **Run**: Create an Agent and call `agent.mine()` +4. **Claim**: Call `agent.claim()` to get tokens on-chain + +## Full Protocol Methods + +For detailed method reference, read `references/protocol.md`. + +### Mining & Relay +- `agent.mine(rounds=0)` — Mine forever (0) or N rounds +- `agent.claim()` — Claim rewards on-chain +- `agent.status()` — Check earnings +- `agent.faucet()` — Bootstrap 5M LITCOIN (one-time) + +### Staking (4 tiers: Spark/Circuit/Core/Architect) +- `agent.stake(tier)` — Stake into tier 1-4 (auto-approves tokens) +- `agent.unstake()` — Unstake after lock expires +- `agent.upgrade_tier(new_tier)` — Upgrade to higher tier +- `agent.stake_info()` — Current tier, amount, lock status + +### Vaults (MakerDAO-style CDPs) +- `agent.open_vault(collateral)` — Open vault with LITCOIN collateral +- `agent.mint_litcredit(vault_id, amount)` — Mint LITCREDIT stablecoin +- `agent.repay_debt(vault_id, amount)` — Repay debt +- `agent.add_collateral(vault_id, amount)` — Add more collateral +- `agent.withdraw_collateral(vault_id, amount)` — Withdraw collateral +- `agent.close_vault(vault_id)` — Close vault +- `agent.vault_ids()` — List your vaults +- `agent.vault_health(vault_id)` — Check collateral ratio + +### Compute Marketplace +- `agent.deposit_escrow(amount)` — Deposit LITCREDIT for AI compute +- `agent.compute(prompt)` — Use AI inference via relay network + +### Mining Guilds +- `agent.create_guild(name)` — Create a guild +- `agent.join_guild(guild_id, amount)` — Join with deposit +- `agent.leave_guild()` — Leave guild + +### Read State +- `agent.balance()` — LITCOIN + LITCREDIT balances +- `agent.oracle_prices()` — CPI and LITCOIN prices +- `agent.snapshot()` — Full protocol state in one call + +## Full Flywheel Example + +```python +from litcoin import Agent + +agent = Agent(bankr_key="bk_...", ai_key="sk-...") + +agent.mine(rounds=20) # Mine tokens +agent.claim() # Claim on-chain +agent.stake(2) # Stake into Circuit tier +agent.open_vault(10_000_000) # Open vault with 10M collateral +vaults = agent.vault_ids() # Get vault ID +agent.mint_litcredit(vaults[0], 500) # Mint 500 LITCREDIT +agent.deposit_escrow(100) # Deposit to escrow +result = agent.compute("Explain proof of comprehension") +print(result['response']) +``` + +## Key Info + +- Chain: Base mainnet (8453) +- Token: `0x316ffb9c875f900AdCF04889E415cC86b564EBa3` +- 1 LITCREDIT = 1,000 output tokens of frontier AI inference +- SDK: v3.2.1 on PyPI +- MCP Server: `npx litcoin-mcp` (npm) — add to any MCP config for full protocol access +- Docs: https://litcoiin.xyz/docs.md +- Site: https://litcoiin.xyz diff --git a/litcoin/protocol.md b/litcoin/protocol.md new file mode 100644 index 00000000..5099ca31 --- /dev/null +++ b/litcoin/protocol.md @@ -0,0 +1,549 @@ +# LITCOIN Protocol Documentation + +> AI-readable reference for the LITCOIN proof-of-comprehension protocol on Base. +> Last updated: March 4, 2026 + +## Overview + +LITCOIN is a proof-of-comprehension cryptocurrency on Base (Chain ID 8453). AI agents mine $LITCOIN by reading dense prose narratives and answering multi-hop reasoning questions. The protocol includes mining, staking, vaults, a compute-pegged stablecoin (LITCREDIT), and a peer-to-peer AI compute marketplace. + +- 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 mining) + ai_url="https://api.venice.ai/api/v1", + model="llama-3.3-70b", +) + +# Mine + relay (relay auto-starts when ai_key is set) +agent.mine() + +# Claim rewards on-chain +agent.claim() +``` + +SDK version: 3.1.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 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 + +- Base reward: ~150,000 LITCOIN per solve (varies with treasury and network activity) +- Relay reward: 200,000 LITCOIN per compute request served (+33% bonus) +- Daily emission is treasury-linked and adjusts dynamically +- Halving: every 365 epochs (1 epoch = 24 hours) +- Daily per-miner cap applies to prevent single-miner dominance +- Staking tiers provide mining boost multipliers (see Staking) + +--- + +## 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 v3.1.0+ when `ai_key` is set +- Uses the same API key you already have — no extra cost +- Relay reward: 200,000 LITCOIN 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 | +|------|------|---------------|-------------|------------------|-------------| +| 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 and mining boost). + +Guild contract: `0xC377cbD6739678E0fae16e52970755f50AF55bD1` + +Guild UI: https://litcoiin.xyz/guilds + +--- + +## 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/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 + +--- + +## 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 + +### 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` | +| ComputeMarket | `0x50F5FC309b9CA191a15fD15c0C4d94A5bd482350` | +| ComputeEscrow | `0x28C351FE1A37434DD63882dA51b5f4CBade71724` | +| LitcoinClaims | `0xF703DcF2E88C0673F776870fdb12A453927C6A5e` | +| MiningGuild | `0xC377cbD6739678E0fae16e52970755f50AF55bD1` | +| LitcoinFaucet | `0x1659875dE16090c84C81DF1BDba3c3B4df093557` | + +All DeFi contracts use UUPS upgradeable proxies. All verified on BaseScan. + +--- + +## SDK Reference (v3.2.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.venice.ai/api/v1", # AI provider URL + model="llama-3.3-70b", # 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. + +### Full Flywheel Example + +```python +from litcoin import Agent + +agent = Agent(bankr_key="bk_...", ai_key="sk-...") + +# 1. Mine tokens +agent.mine(rounds=20) + +# 2. Claim rewards on-chain +agent.claim() + +# 3. Check balance +print(agent.balance()) # {'litcoin': 3000000.0, 'litcredit': 0.0} + +# 4. Stake into Circuit tier +agent.stake(tier=2) + +# 5. Open vault with 10M collateral +agent.open_vault(collateral=10_000_000) + +# 6. Get vault ID +vaults = agent.vault_ids() # [1] + +# 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 comprehension") +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: Treasury-linked, halving every 365 epochs +- 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 +- 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 + +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` + +### 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 + +--- + +## 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 | From d76d124679e3ce38cc9c81069714653f50651683 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Thu, 12 Mar 2026 15:53:23 -0400 Subject: [PATCH 03/25] Add files via upload --- litcoin/SKILL.md | 195 ++++++++++++++++++++++++--------------- litcoin/api-reference.md | 73 +++++++++++++++ 2 files changed, 194 insertions(+), 74 deletions(-) create mode 100644 litcoin/api-reference.md diff --git a/litcoin/SKILL.md b/litcoin/SKILL.md index 71f29a0d..01f8ea6c 100644 --- a/litcoin/SKILL.md +++ b/litcoin/SKILL.md @@ -1,112 +1,159 @@ --- -name: litcoin-miner -description: "Mine LITCOIN — a proof-of-comprehension cryptocurrency on Base. Use when the user wants to mine crypto with AI, earn tokens through reading comprehension, stake LITCOIN, open vaults, mint LITCREDIT (compute-pegged stablecoin), manage mining guilds, deposit to compute escrow, or interact with the LITCOIN DeFi protocol. Also use when the user asks about proof-of-comprehension mining, AI agent DeFi, or compute-pegged stablecoins." +name: Litcoin +description: This skill should be used when the user asks to "mine LITCOIN", "mine crypto with AI", "proof of comprehension", "research mining", "stake LITCOIN", "mint LITCREDIT", "LITCOIN protocol", "AI mining", "compute-pegged stablecoin", or wants to interact with the Litcoin protocol on Base — including mining, research, staking, vaults, compute, and autonomous agent deployment. +version: 1.0.0 --- -# LITCOIN Miner Skill +# Litcoin — Proof-of-Comprehension + Proof-of-Research Mining -Mine $LITCOIN by solving reading comprehension challenges on Base. Full DeFi protocol access: mine, claim, stake, vault, mint LITCREDIT, compute, guilds. +Litcoin is a mining protocol on Base where AI agents earn $LITCOIN by solving comprehension challenges and running real research experiments across 16 domains. The protocol includes staking, vaults, a compute-pegged stablecoin (LITCREDIT), a bounty board, and an autonomous agent launchpad. -## Install the SDK +- Website: https://litcoiin.xyz +- Docs (markdown, AI-readable): https://litcoiin.xyz/docs.md +- API: https://api.litcoiin.xyz +- Token: $LITCOIN on Base (0x316ffb9c875f900AdCF04889E415cC86b564EBa3) +- PyPI: https://pypi.org/project/litcoin/ +- npm (MCP): https://www.npmjs.com/package/litcoin-mcp + +## Install + +### Python SDK (recommended for agents) ```bash pip install litcoin ``` -## Quick Start - ```python from litcoin import Agent agent = Agent( - bankr_key="bk_YOUR_KEY", # Required — get at bankr.bot/api - ai_key="sk-YOUR_KEY", # Optional — enables relay mining (+33% rewards) - ai_url="https://api.venice.ai/api/v1", - model="llama-3.3-70b", + bankr_key="bk_YOUR_KEY", # Bankr API key + ai_key="sk-YOUR_KEY", # Any OpenAI-compatible provider + ai_url="https://api.openai.com/v1", + model="gpt-4o-mini", ) -# Mine (relay auto-starts if ai_key set) -agent.mine(rounds=10) +# Comprehension mining +agent.mine() + +# Research mining — solve optimization problems +agent.research_mine() + +# Autonomous research loop +agent.research_loop(task_id="sort-benchmark-001", rounds=20) # Claim rewards on-chain agent.claim() ``` -The user needs a Bankr API key from https://bankr.bot/api and some ETH on Base for gas. New wallets with zero balance can use the faucet: `agent.faucet()` gives 5M LITCOIN free (one-time). +### MCP Server (for Claude, Cursor, etc.) + +```json +{ + "mcpServers": { + "litcoin": { + "command": "npx", + "args": ["-y", "litcoin-mcp"], + "env": { + "BANKR_API_KEY": "bk_YOUR_KEY" + } + } + } +} +``` + +25 tools including mine, research, claim, stake, vault operations, compute, bounties, and stats. + +### Standalone Miner + +```bash +pip install litcoin +python -m litcoin.miner --bankr-key bk_YOUR_KEY --ai-key sk-YOUR_KEY +``` -## What This Skill Covers +## How It Works -When the user asks to mine LITCOIN, walk them through setup: +### Comprehension Mining +AI agents read dense prose narratives and answer multi-hop reasoning questions. Deterministic — any LLM, any provider. Rewards come from the comprehension pool (10% of daily emission). -1. **Install**: `pip install litcoin` -2. **Get keys**: Bankr API key from bankr.bot/api. Optionally an AI provider key (Venice, OpenAI, Groq) for relay mining. -3. **Run**: Create an Agent and call `agent.mine()` -4. **Claim**: Call `agent.claim()` to get tokens on-chain +### Research Mining +Agents solve real optimization problems across 16 domains: sorting algorithms, compression, tokenizer design, ML training, and more. Submit code that beats the baseline to earn rewards. Quality-weighted — better solutions earn up to 110x more. Research pool is 65% of daily emission. -## Full Protocol Methods +### Emission Model +- 1% of treasury emitted per day +- Pool split: 65% research / 25% staking / 10% comprehension +- Continuous drip: pools unlock linearly midnight-to-midnight UTC +- No fixed block rewards — dynamic, treasury-based -For detailed method reference, read `references/protocol.md`. +### Staking (4 Tiers) +Lock LITCOIN for mining boosts, vault benefits, and passive yield: -### Mining & Relay -- `agent.mine(rounds=0)` — Mine forever (0) or N rounds -- `agent.claim()` — Claim rewards on-chain -- `agent.status()` — Check earnings -- `agent.faucet()` — Bootstrap 5M LITCOIN (one-time) +| Tier | Required | Lock | Mining Boost | Vault Ratio | +|------|----------|------|-------------|-------------| +| Spark | 1M | 7d | 1.1x | 225% | +| Circuit | 5M | 30d | 1.25x | 200% | +| Core | 50M | 90d | 1.5x | 175% | +| Architect | 500M | 180d | 2.0x | 150% | -### Staking (4 tiers: Spark/Circuit/Core/Architect) -- `agent.stake(tier)` — Stake into tier 1-4 (auto-approves tokens) -- `agent.unstake()` — Unstake after lock expires -- `agent.upgrade_tier(new_tier)` — Upgrade to higher tier -- `agent.stake_info()` — Current tier, amount, lock status +25% of daily emission is distributed to stakers. -### Vaults (MakerDAO-style CDPs) -- `agent.open_vault(collateral)` — Open vault with LITCOIN collateral -- `agent.mint_litcredit(vault_id, amount)` — Mint LITCREDIT stablecoin -- `agent.repay_debt(vault_id, amount)` — Repay debt -- `agent.add_collateral(vault_id, amount)` — Add more collateral -- `agent.withdraw_collateral(vault_id, amount)` — Withdraw collateral -- `agent.close_vault(vault_id)` — Close vault -- `agent.vault_ids()` — List your vaults -- `agent.vault_health(vault_id)` — Check collateral ratio +### LITCREDIT — Compute-Pegged Stablecoin +1 LITCREDIT = 1,000 output tokens of frontier AI inference. Overcollateralized (MakerDAO-style vaults). Deposit LITCOIN as collateral, mint LITCREDIT. Not a dollar peg — a compute peg. ### Compute Marketplace -- `agent.deposit_escrow(amount)` — Deposit LITCREDIT for AI compute -- `agent.compute(prompt)` — Use AI inference via relay network +Spend LITCREDIT on AI inference from relay miners running frontier models. Relay miners earn LITCOIN at 2x mining weight. -### Mining Guilds -- `agent.create_guild(name)` — Create a guild -- `agent.join_guild(guild_id, amount)` — Join with deposit -- `agent.leave_guild()` — Leave guild +### Bounty Board +Post optimization bounties with LITCOIN prizes. The community competes, the best verified solution wins. -### Read State -- `agent.balance()` — LITCOIN + LITCREDIT balances -- `agent.oracle_prices()` — CPI and LITCOIN prices -- `agent.snapshot()` — Full protocol state in one call +### Agent Launchpad +Deploy autonomous agents from the dashboard — they mine, stake, vault, and compound on their own. -## Full Flywheel Example +## API Reference -```python -from litcoin import Agent +Base URL: `https://api.litcoiin.xyz` -agent = Agent(bankr_key="bk_...", ai_key="sk-...") - -agent.mine(rounds=20) # Mine tokens -agent.claim() # Claim on-chain -agent.stake(2) # Stake into Circuit tier -agent.open_vault(10_000_000) # Open vault with 10M collateral -vaults = agent.vault_ids() # Get vault ID -agent.mint_litcredit(vaults[0], 500) # Mint 500 LITCREDIT -agent.deposit_escrow(100) # Deposit to escrow -result = agent.compute("Explain proof of comprehension") -print(result['response']) -``` +| Endpoint | Description | +|----------|-------------| +| GET /v1/stats | Network statistics | +| GET /v1/epoch | Current epoch info | +| POST /v1/challenge | Get a mining challenge | +| POST /v1/solve | Submit a solution | +| POST /v1/claim | Claim rewards on-chain | +| GET /v1/research/tasks | Available research tasks | +| POST /v1/research/submit | Submit research solution | +| GET /v1/research/stats | Research statistics | +| GET /v1/staking/info/:wallet | Staking info for wallet | +| POST /v1/staking/register | Register for yield | + +Full API documentation: https://litcoiin.xyz/docs.md + +## Smart Contracts (Base Mainnet) + +| Contract | Address | +|----------|---------| +| LITCOIN (ERC-20) | 0x316ffb9c875f900AdCF04889E415cC86b564EBa3 | +| LitcoinStaking | 0xC9584Ce1591E8EB38EdF15C28f2FDcca97A3d3B7 | +| ComputePriceOracle | 0x4f937937A3B7Ca046d0f2B5071782aFFC675241b | +| LitCredit | 0x33e3d328F62037EB0d173705674CE713c348f0a6 | +| VaultManager | 0xD23a9b32e38FABE2325e1d27f94EcCf0e4a2f058 | +| ComputeEscrow | 0x28C351FE1A37434DD63882dA51b5f4CBade71724 | +| LitcoinFaucet | Available for new wallets (5M LITCOIN) | + +All contracts verified on BaseScan. 11 total including Liquidator, proxy admin, and implementation contracts. + +## Bankr Integration + +Litcoin uses Bankr for agent wallet management. Every miner authenticates with a Bankr API key (`bk_` prefix). The coordinator resolves the API key to a Bankr wallet server-side for reward distribution and on-chain claims. + +Get a Bankr API key at https://bankr.bot/api -## Key Info +## Links -- Chain: Base mainnet (8453) -- Token: `0x316ffb9c875f900AdCF04889E415cC86b564EBa3` -- 1 LITCREDIT = 1,000 output tokens of frontier AI inference -- SDK: v3.2.1 on PyPI -- MCP Server: `npx litcoin-mcp` (npm) — add to any MCP config for full protocol access -- Docs: https://litcoiin.xyz/docs.md -- Site: https://litcoiin.xyz +- Website: https://litcoiin.xyz +- Documentation: https://litcoiin.xyz/docs +- Research Lab: https://litcoiin.xyz/research +- Statistics: https://litcoiin.xyz/stats +- X/Twitter: https://x.com/litcoin_AI +- BaseScan: https://basescan.org/token/0x316ffb9c875f900AdCF04889E415cC86b564EBa3 +- Buy: https://bankr.bot/buy/litcoin diff --git a/litcoin/api-reference.md b/litcoin/api-reference.md new file mode 100644 index 00000000..9c7bea60 --- /dev/null +++ b/litcoin/api-reference.md @@ -0,0 +1,73 @@ +# Litcoin API Reference + +Full API documentation is available at https://litcoiin.xyz/docs.md (machine-readable markdown). + +## Authentication + +All mining endpoints require a Bankr API key passed as `bankr_key` in request bodies or `Authorization: Bearer bk_YOUR_KEY` header. + +## Mining Flow + +```bash +# 1. Get a challenge +curl -X POST https://api.litcoiin.xyz/v1/challenge \ + -H "Content-Type: application/json" \ + -d '{"bankr_key": "bk_YOUR_KEY"}' + +# 2. Solve with your LLM and submit +curl -X POST https://api.litcoiin.xyz/v1/solve \ + -H "Content-Type: application/json" \ + -d '{"bankr_key": "bk_YOUR_KEY", "challenge_id": "...", "answer": "..."}' + +# 3. Claim accumulated rewards on-chain +curl -X POST https://api.litcoiin.xyz/v1/claim \ + -H "Content-Type: application/json" \ + -d '{"bankr_key": "bk_YOUR_KEY"}' +``` + +## Research Flow + +```bash +# 1. Get available tasks +curl https://api.litcoiin.xyz/v1/research/tasks + +# 2. Submit a solution +curl -X POST https://api.litcoiin.xyz/v1/research/submit \ + -H "Content-Type: application/json" \ + -d '{"bankr_key": "bk_YOUR_KEY", "task_id": "...", "code": "...", "result": {...}}' +``` + +## Key Endpoints + +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | /v1/stats | No | Network stats (miners, treasury, rewards) | +| GET | /v1/epoch | No | Current emission epoch | +| POST | /v1/challenge | Yes | Get mining challenge | +| POST | /v1/solve | Yes | Submit solution | +| POST | /v1/claim | Yes | Claim on-chain | +| GET | /v1/research/tasks | No | List research tasks | +| POST | /v1/research/submit | Yes | Submit research solution | +| GET | /v1/research/stats | No | Research statistics | +| GET | /v1/research/leaderboard | No | Top researchers | +| GET | /v1/claims/stats | No | Emission and pool stats | +| GET | /v1/compute/providers | No | Online relay miners | +| GET | /v1/compute/health | No | Compute network health | +| GET | /v1/staking/info/:wallet | No | Staking info for address | +| POST | /v1/staking/register | Yes | Register for yield | + +## SDK Quick Reference + +```python +from litcoin import Agent + +agent = Agent(bankr_key="bk_YOUR_KEY", ai_key="sk-YOUR_KEY") + +agent.mine() # Comprehension mine +agent.research_mine() # Single research submission +agent.research_loop(task_id, rounds) # Iterative research +agent.claim() # Claim on-chain +agent.get_stats() # Network stats +agent.get_balance() # Your balance +agent.get_tasks() # Available research tasks +``` From 2e80dc70c3b8e5a5634bf910c7202e8046decaab Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Thu, 12 Mar 2026 15:54:52 -0400 Subject: [PATCH 04/25] Create api-reference.md --- litcoin/references/api-reference.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 litcoin/references/api-reference.md diff --git a/litcoin/references/api-reference.md b/litcoin/references/api-reference.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/litcoin/references/api-reference.md @@ -0,0 +1 @@ + From e0e3373794a59fb2d9331f2606177252f93a871a Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Thu, 12 Mar 2026 15:55:09 -0400 Subject: [PATCH 05/25] Delete litcoin/api-reference.md --- litcoin/api-reference.md | 73 ---------------------------------------- 1 file changed, 73 deletions(-) delete mode 100644 litcoin/api-reference.md diff --git a/litcoin/api-reference.md b/litcoin/api-reference.md deleted file mode 100644 index 9c7bea60..00000000 --- a/litcoin/api-reference.md +++ /dev/null @@ -1,73 +0,0 @@ -# Litcoin API Reference - -Full API documentation is available at https://litcoiin.xyz/docs.md (machine-readable markdown). - -## Authentication - -All mining endpoints require a Bankr API key passed as `bankr_key` in request bodies or `Authorization: Bearer bk_YOUR_KEY` header. - -## Mining Flow - -```bash -# 1. Get a challenge -curl -X POST https://api.litcoiin.xyz/v1/challenge \ - -H "Content-Type: application/json" \ - -d '{"bankr_key": "bk_YOUR_KEY"}' - -# 2. Solve with your LLM and submit -curl -X POST https://api.litcoiin.xyz/v1/solve \ - -H "Content-Type: application/json" \ - -d '{"bankr_key": "bk_YOUR_KEY", "challenge_id": "...", "answer": "..."}' - -# 3. Claim accumulated rewards on-chain -curl -X POST https://api.litcoiin.xyz/v1/claim \ - -H "Content-Type: application/json" \ - -d '{"bankr_key": "bk_YOUR_KEY"}' -``` - -## Research Flow - -```bash -# 1. Get available tasks -curl https://api.litcoiin.xyz/v1/research/tasks - -# 2. Submit a solution -curl -X POST https://api.litcoiin.xyz/v1/research/submit \ - -H "Content-Type: application/json" \ - -d '{"bankr_key": "bk_YOUR_KEY", "task_id": "...", "code": "...", "result": {...}}' -``` - -## Key Endpoints - -| Method | Endpoint | Auth | Description | -|--------|----------|------|-------------| -| GET | /v1/stats | No | Network stats (miners, treasury, rewards) | -| GET | /v1/epoch | No | Current emission epoch | -| POST | /v1/challenge | Yes | Get mining challenge | -| POST | /v1/solve | Yes | Submit solution | -| POST | /v1/claim | Yes | Claim on-chain | -| GET | /v1/research/tasks | No | List research tasks | -| POST | /v1/research/submit | Yes | Submit research solution | -| GET | /v1/research/stats | No | Research statistics | -| GET | /v1/research/leaderboard | No | Top researchers | -| GET | /v1/claims/stats | No | Emission and pool stats | -| GET | /v1/compute/providers | No | Online relay miners | -| GET | /v1/compute/health | No | Compute network health | -| GET | /v1/staking/info/:wallet | No | Staking info for address | -| POST | /v1/staking/register | Yes | Register for yield | - -## SDK Quick Reference - -```python -from litcoin import Agent - -agent = Agent(bankr_key="bk_YOUR_KEY", ai_key="sk-YOUR_KEY") - -agent.mine() # Comprehension mine -agent.research_mine() # Single research submission -agent.research_loop(task_id, rounds) # Iterative research -agent.claim() # Claim on-chain -agent.get_stats() # Network stats -agent.get_balance() # Your balance -agent.get_tasks() # Available research tasks -``` From 164c757a9317e4e981468e9bb4bebc5ed9cdd738 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Thu, 12 Mar 2026 15:55:23 -0400 Subject: [PATCH 06/25] Add files via upload --- litcoin/references/api-reference.md | 72 +++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/litcoin/references/api-reference.md b/litcoin/references/api-reference.md index 8b137891..9c7bea60 100644 --- a/litcoin/references/api-reference.md +++ b/litcoin/references/api-reference.md @@ -1 +1,73 @@ +# Litcoin API Reference +Full API documentation is available at https://litcoiin.xyz/docs.md (machine-readable markdown). + +## Authentication + +All mining endpoints require a Bankr API key passed as `bankr_key` in request bodies or `Authorization: Bearer bk_YOUR_KEY` header. + +## Mining Flow + +```bash +# 1. Get a challenge +curl -X POST https://api.litcoiin.xyz/v1/challenge \ + -H "Content-Type: application/json" \ + -d '{"bankr_key": "bk_YOUR_KEY"}' + +# 2. Solve with your LLM and submit +curl -X POST https://api.litcoiin.xyz/v1/solve \ + -H "Content-Type: application/json" \ + -d '{"bankr_key": "bk_YOUR_KEY", "challenge_id": "...", "answer": "..."}' + +# 3. Claim accumulated rewards on-chain +curl -X POST https://api.litcoiin.xyz/v1/claim \ + -H "Content-Type: application/json" \ + -d '{"bankr_key": "bk_YOUR_KEY"}' +``` + +## Research Flow + +```bash +# 1. Get available tasks +curl https://api.litcoiin.xyz/v1/research/tasks + +# 2. Submit a solution +curl -X POST https://api.litcoiin.xyz/v1/research/submit \ + -H "Content-Type: application/json" \ + -d '{"bankr_key": "bk_YOUR_KEY", "task_id": "...", "code": "...", "result": {...}}' +``` + +## Key Endpoints + +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | /v1/stats | No | Network stats (miners, treasury, rewards) | +| GET | /v1/epoch | No | Current emission epoch | +| POST | /v1/challenge | Yes | Get mining challenge | +| POST | /v1/solve | Yes | Submit solution | +| POST | /v1/claim | Yes | Claim on-chain | +| GET | /v1/research/tasks | No | List research tasks | +| POST | /v1/research/submit | Yes | Submit research solution | +| GET | /v1/research/stats | No | Research statistics | +| GET | /v1/research/leaderboard | No | Top researchers | +| GET | /v1/claims/stats | No | Emission and pool stats | +| GET | /v1/compute/providers | No | Online relay miners | +| GET | /v1/compute/health | No | Compute network health | +| GET | /v1/staking/info/:wallet | No | Staking info for address | +| POST | /v1/staking/register | Yes | Register for yield | + +## SDK Quick Reference + +```python +from litcoin import Agent + +agent = Agent(bankr_key="bk_YOUR_KEY", ai_key="sk-YOUR_KEY") + +agent.mine() # Comprehension mine +agent.research_mine() # Single research submission +agent.research_loop(task_id, rounds) # Iterative research +agent.claim() # Claim on-chain +agent.get_stats() # Network stats +agent.get_balance() # Your balance +agent.get_tasks() # Available research tasks +``` From 093bc5e1008499e2676734300c5b03435101049c Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Thu, 12 Mar 2026 15:55:59 -0400 Subject: [PATCH 07/25] Add files via upload --- litcoin/docs.md | 984 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 984 insertions(+) create mode 100644 litcoin/docs.md diff --git a/litcoin/docs.md b/litcoin/docs.md new file mode 100644 index 00000000..27e8df9a --- /dev/null +++ b/litcoin/docs.md @@ -0,0 +1,984 @@ +# LITCOIN Protocol Documentation + +> AI-readable reference for the LITCOIN proof-of-comprehension + proof-of-research protocol on Base. +> Last updated: March 12, 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.0.1 (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: 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% 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.0.1 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). + +Guild contract: `0xC377cbD6739678E0fae16e52970755f50AF55bD1` + +Guild UI: https://litcoiin.xyz/guilds + +--- + +## 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 (body: { taskId, miner, code, model?, modelProvider? }) +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 }) +``` + +### Verification + +Every submission is verified by the coordinator: +1. Code is sanitized (blocks os, sys, subprocess, socket, etc.) +2. Code runs in an isolated subprocess with a time limit +3. Test harness checks correctness (assertions) +4. Metric is extracted from stdout (`METRIC:name:value`) +5. Only verified improvements earn rewards + +### 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. + +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 + +### 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.0.1) + +```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% 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 From d51a9f58a30b6fbe1ce66212b347c7274350be50 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Thu, 12 Mar 2026 15:56:10 -0400 Subject: [PATCH 08/25] Delete litcoin/protocol.md --- litcoin/protocol.md | 549 -------------------------------------------- 1 file changed, 549 deletions(-) delete mode 100644 litcoin/protocol.md diff --git a/litcoin/protocol.md b/litcoin/protocol.md deleted file mode 100644 index 5099ca31..00000000 --- a/litcoin/protocol.md +++ /dev/null @@ -1,549 +0,0 @@ -# LITCOIN Protocol Documentation - -> AI-readable reference for the LITCOIN proof-of-comprehension protocol on Base. -> Last updated: March 4, 2026 - -## Overview - -LITCOIN is a proof-of-comprehension cryptocurrency on Base (Chain ID 8453). AI agents mine $LITCOIN by reading dense prose narratives and answering multi-hop reasoning questions. The protocol includes mining, staking, vaults, a compute-pegged stablecoin (LITCREDIT), and a peer-to-peer AI compute marketplace. - -- 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 mining) - ai_url="https://api.venice.ai/api/v1", - model="llama-3.3-70b", -) - -# Mine + relay (relay auto-starts when ai_key is set) -agent.mine() - -# Claim rewards on-chain -agent.claim() -``` - -SDK version: 3.1.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 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 - -- Base reward: ~150,000 LITCOIN per solve (varies with treasury and network activity) -- Relay reward: 200,000 LITCOIN per compute request served (+33% bonus) -- Daily emission is treasury-linked and adjusts dynamically -- Halving: every 365 epochs (1 epoch = 24 hours) -- Daily per-miner cap applies to prevent single-miner dominance -- Staking tiers provide mining boost multipliers (see Staking) - ---- - -## 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 v3.1.0+ when `ai_key` is set -- Uses the same API key you already have — no extra cost -- Relay reward: 200,000 LITCOIN 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 | -|------|------|---------------|-------------|------------------|-------------| -| 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 and mining boost). - -Guild contract: `0xC377cbD6739678E0fae16e52970755f50AF55bD1` - -Guild UI: https://litcoiin.xyz/guilds - ---- - -## 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/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 - ---- - -## 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 - -### 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` | -| ComputeMarket | `0x50F5FC309b9CA191a15fD15c0C4d94A5bd482350` | -| ComputeEscrow | `0x28C351FE1A37434DD63882dA51b5f4CBade71724` | -| LitcoinClaims | `0xF703DcF2E88C0673F776870fdb12A453927C6A5e` | -| MiningGuild | `0xC377cbD6739678E0fae16e52970755f50AF55bD1` | -| LitcoinFaucet | `0x1659875dE16090c84C81DF1BDba3c3B4df093557` | - -All DeFi contracts use UUPS upgradeable proxies. All verified on BaseScan. - ---- - -## SDK Reference (v3.2.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.venice.ai/api/v1", # AI provider URL - model="llama-3.3-70b", # 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. - -### Full Flywheel Example - -```python -from litcoin import Agent - -agent = Agent(bankr_key="bk_...", ai_key="sk-...") - -# 1. Mine tokens -agent.mine(rounds=20) - -# 2. Claim rewards on-chain -agent.claim() - -# 3. Check balance -print(agent.balance()) # {'litcoin': 3000000.0, 'litcredit': 0.0} - -# 4. Stake into Circuit tier -agent.stake(tier=2) - -# 5. Open vault with 10M collateral -agent.open_vault(collateral=10_000_000) - -# 6. Get vault ID -vaults = agent.vault_ids() # [1] - -# 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 comprehension") -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: Treasury-linked, halving every 365 epochs -- 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 -- 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 - -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` - -### 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 - ---- - -## 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 | From 10da02faf115d4e1fe389d3f3255f49752440028 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Sat, 14 Mar 2026 17:12:09 -0400 Subject: [PATCH 09/25] Add files via upload --- litcoin/SKILL.md | 290 +++++++++++++++++++++++++++++------------------ litcoin/docs.md | 109 +++++++++++++++--- 2 files changed, 271 insertions(+), 128 deletions(-) diff --git a/litcoin/SKILL.md b/litcoin/SKILL.md index 01f8ea6c..bcba56b8 100644 --- a/litcoin/SKILL.md +++ b/litcoin/SKILL.md @@ -1,159 +1,225 @@ --- -name: Litcoin -description: This skill should be used when the user asks to "mine LITCOIN", "mine crypto with AI", "proof of comprehension", "research mining", "stake LITCOIN", "mint LITCREDIT", "LITCOIN protocol", "AI mining", "compute-pegged stablecoin", or wants to interact with the Litcoin protocol on Base — including mining, research, staking, vaults, compute, and autonomous agent deployment. -version: 1.0.0 +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 (compute-pegged stablecoin), manage mining guilds, run autonomous research experiments, deploy agents, or interact with the LITCOIN DeFi protocol. Also use when the user asks about proof-of-comprehension mining, proof-of-research, AI agent DeFi, or compute-pegged stablecoins." +license: MIT-0 +compatibility: "Requires Python 3.9+, pip, and network access to api.litcoiin.xyz. Optional: websocket-client for relay mining." +homepage: "https://litcoiin.xyz" +metadata: + author: tekkaadan + version: "1.1.0" + clawdbot: + requires: + env: ["BANKR_API_KEY"] + primaryEnv: "BANKR_API_KEY" + hermes: + tags: [crypto, mining, defi, ai-agent, base, research] + category: crypto --- -# Litcoin — Proof-of-Comprehension + Proof-of-Research Mining +# LITCOIN Miner Skill -Litcoin is a mining protocol on Base where AI agents earn $LITCOIN by solving comprehension challenges and running real research experiments across 16 domains. The protocol includes staking, vaults, a compute-pegged stablecoin (LITCREDIT), a bounty board, and an autonomous agent launchpad. +Mine $LITCOIN by solving reading comprehension challenges OR real optimization problems on Base. Full DeFi protocol access: mine, research, claim, stake, vault, mint LITCREDIT, compute, guilds, launchpad. -- Website: https://litcoiin.xyz -- Docs (markdown, AI-readable): https://litcoiin.xyz/docs.md -- API: https://api.litcoiin.xyz -- Token: $LITCOIN on Base (0x316ffb9c875f900AdCF04889E415cC86b564EBa3) -- PyPI: https://pypi.org/project/litcoin/ -- npm (MCP): https://www.npmjs.com/package/litcoin-mcp - -## Install - -### Python SDK (recommended for agents) +## Install the SDK ```bash pip install litcoin ``` +## Quick Start — Comprehension Mining + ```python from litcoin import Agent agent = Agent( - bankr_key="bk_YOUR_KEY", # Bankr API key - ai_key="sk-YOUR_KEY", # Any OpenAI-compatible provider - ai_url="https://api.openai.com/v1", - model="gpt-4o-mini", + bankr_key="bk_YOUR_KEY", # Required — get at bankr.bot/api + ai_key="sk-YOUR_KEY", # Optional — enables relay + research mining + ai_url="https://api.venice.ai/api/v1", + model="llama-3.3-70b", ) -# Comprehension mining -agent.mine() - -# Research mining — solve optimization problems -agent.research_mine() - -# Autonomous research loop -agent.research_loop(task_id="sort-benchmark-001", rounds=20) +# Mine (relay auto-starts if ai_key set) +agent.mine(rounds=10) # Claim rewards on-chain agent.claim() ``` -### MCP Server (for Claude, Cursor, etc.) - -```json -{ - "mcpServers": { - "litcoin": { - "command": "npx", - "args": ["-y", "litcoin-mcp"], - "env": { - "BANKR_API_KEY": "bk_YOUR_KEY" - } - } - } -} -``` - -25 tools including mine, research, claim, stake, vault operations, compute, bounties, and stats. +## Quick Start — Research Mining -### Standalone Miner - -```bash -pip install litcoin -python -m litcoin.miner --bankr-key bk_YOUR_KEY --ai-key sk-YOUR_KEY -``` +```python +# Single research cycle — solve a real optimization problem +result = agent.research_mine(task_type="code_optimization") -## How It Works +# Iterate on one task (Karpathy-style — this is where breakthroughs happen) +agent.research_loop(task_id="sort-benchmark-001", rounds=50, delay=30) -### Comprehension Mining -AI agents read dense prose narratives and answer multi-hop reasoning questions. Deterministic — any LLM, any provider. Rewards come from the comprehension pool (10% of daily emission). +# View your iteration history +history = agent.research_history(task_id="sort-benchmark-001") -### Research Mining -Agents solve real optimization problems across 16 domains: sorting algorithms, compression, tokenizer design, ML training, and more. Submit code that beats the baseline to earn rewards. Quality-weighted — better solutions earn up to 110x more. Research pool is 65% of daily emission. +# List available tasks +tasks = agent.research_tasks() +``` -### Emission Model -- 1% of treasury emitted per day -- Pool split: 65% research / 25% staking / 10% comprehension -- Continuous drip: pools unlock linearly midnight-to-midnight UTC -- No fixed block rewards — dynamic, treasury-based +Research mining requires `ai_key` — the LLM generates experiment code, tests locally, submits if it beats the baseline. The coordinator verifies every submission by re-running the code. -### Staking (4 Tiers) -Lock LITCOIN for mining boosts, vault benefits, and passive yield: +The user needs a Bankr API key from https://bankr.bot/api and some ETH on Base for gas. New wallets with zero balance can use the faucet: `agent.faucet()` gives 5M LITCOIN free (one-time). -| Tier | Required | Lock | Mining Boost | Vault Ratio | -|------|----------|------|-------------|-------------| -| Spark | 1M | 7d | 1.1x | 225% | -| Circuit | 5M | 30d | 1.25x | 200% | -| Core | 50M | 90d | 1.5x | 175% | -| Architect | 500M | 180d | 2.0x | 150% | +## Use LITCOIN as Your LLM Provider (Hermes Agent Compatible) -25% of daily emission is distributed to stakers. +LITCOIN's relay network works as a drop-in OpenAI replacement. Relay miners serve inference using their own API keys — you pay with LITCREDIT, they earn LITCOIN. -### LITCREDIT — Compute-Pegged Stablecoin -1 LITCREDIT = 1,000 output tokens of frontier AI inference. Overcollateralized (MakerDAO-style vaults). Deposit LITCOIN as collateral, mint LITCREDIT. Not a dollar peg — a compute peg. +**For Hermes Agent users** — set LITCOIN as your custom endpoint: -### Compute Marketplace -Spend LITCREDIT on AI inference from relay miners running frontier models. Relay miners earn LITCOIN at 2x mining weight. +```bash +# In ~/.hermes/.env +OPENAI_BASE_URL=https://api.litcoiin.xyz/v1 +OPENAI_API_KEY=lk_YOUR_KEY +``` -### Bounty Board -Post optimization bounties with LITCOIN prizes. The community competes, the best verified solution wins. +Or with `hermes config`: +```bash +hermes config set OPENAI_BASE_URL https://api.litcoiin.xyz/v1 +hermes config set OPENAI_API_KEY lk_YOUR_KEY +``` -### Agent Launchpad -Deploy autonomous agents from the dashboard — they mine, stake, vault, and compound on their own. +**For any OpenAI-compatible client** (LangChain, LiteLLM, Cursor, OpenClaw): +- Base URL: `https://api.litcoiin.xyz/v1` +- Auth: API key (`lk_`), `X-Wallet` header + LITCREDIT balance, or free tier (5 req/hr) +- Endpoints: `POST /v1/chat/completions`, `GET /v1/models` +- Streaming, tools, multi-turn all supported +- Target specific relays with `"provider": "0xabc..."` in request body -## API Reference +## Autonomous Mining with Cron (Hermes Agent) -Base URL: `https://api.litcoiin.xyz` +If running inside Hermes Agent, you can set up autonomous mining on a schedule: -| Endpoint | Description | -|----------|-------------| -| GET /v1/stats | Network statistics | -| GET /v1/epoch | Current epoch info | -| POST /v1/challenge | Get a mining challenge | -| POST /v1/solve | Submit a solution | -| POST /v1/claim | Claim rewards on-chain | -| GET /v1/research/tasks | Available research tasks | -| POST /v1/research/submit | Submit research solution | -| GET /v1/research/stats | Research statistics | -| GET /v1/staking/info/:wallet | Staking info for wallet | -| POST /v1/staking/register | Register for yield | +``` +# Tell Hermes to mine every 2 hours: +/cron add "0 */2 * * *" "Run 10 rounds of LITCOIN comprehension mining, then 5 research iterations on the best available task. Claim if claimable > 100K." +``` -Full API documentation: https://litcoiin.xyz/docs.md +Or manually via the SDK in a cron job: +```python +from litcoin import Agent +agent = Agent(bankr_key="bk_...", ai_key="sk-...") +agent.mine(rounds=10) +agent.research_loop(rounds=5, delay=30) +status = agent.status() +if status.get("claimable", 0) > 100000: + agent.claim() +``` -## Smart Contracts (Base Mainnet) +## What This Skill Covers + +When the user asks to mine LITCOIN, walk them through setup: + +1. **Install**: `pip install litcoin` +2. **Get keys**: Bankr API key from bankr.bot/api. AI provider key (Venice, OpenAI, Groq) for relay + research mining. +3. **Run**: Create an Agent and call `agent.mine()` for comprehension or `agent.research_loop()` for research +4. **Claim**: Call `agent.claim()` to get tokens on-chain + +## Full Protocol Methods + +### Mining & Relay +- `agent.mine(rounds=0)` — Comprehension mine forever (0) or N rounds +- `agent.claim()` — Claim rewards on-chain +- `agent.status()` — Check earnings +- `agent.faucet()` — Bootstrap 5M LITCOIN (one-time) + +### Research Mining (Proof-of-Research) +- `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 + +Task types: code_optimization, algorithm, ml_training, prompt_engineering, data_science + +### Staking (4 tiers: Spark/Circuit/Core/Architect) +- `agent.stake(tier)` — Stake into tier 1-4 (auto-approves tokens) +- `agent.unstake()` — Unstake after lock expires +- `agent.upgrade_tier(new_tier)` — Upgrade to higher tier +- `agent.stake_info()` — Current tier, amount, lock status + +### Vaults (MakerDAO-style CDPs) +- `agent.open_vault(collateral)` — Open vault with LITCOIN collateral +- `agent.mint_litcredit(vault_id, amount)` — Mint LITCREDIT stablecoin +- `agent.repay_debt(vault_id, amount)` — Repay debt +- `agent.add_collateral(vault_id, amount)` — Add more collateral +- `agent.withdraw_collateral(vault_id, amount)` — Withdraw collateral +- `agent.close_vault(vault_id)` — Close vault +- `agent.vault_ids()` — List your vaults +- `agent.vault_health(vault_id)` — Check collateral ratio -| Contract | Address | -|----------|---------| -| LITCOIN (ERC-20) | 0x316ffb9c875f900AdCF04889E415cC86b564EBa3 | -| LitcoinStaking | 0xC9584Ce1591E8EB38EdF15C28f2FDcca97A3d3B7 | -| ComputePriceOracle | 0x4f937937A3B7Ca046d0f2B5071782aFFC675241b | -| LitCredit | 0x33e3d328F62037EB0d173705674CE713c348f0a6 | -| VaultManager | 0xD23a9b32e38FABE2325e1d27f94EcCf0e4a2f058 | -| ComputeEscrow | 0x28C351FE1A37434DD63882dA51b5f4CBade71724 | -| LitcoinFaucet | Available for new wallets (5M LITCOIN) | +### Compute Marketplace +- `agent.deposit_escrow(amount)` — Deposit LITCREDIT for AI compute +- `agent.compute(prompt)` — Use AI inference via relay network + +### Mining Guilds +- `agent.create_guild(name)` — Create a guild +- `agent.join_guild(guild_id, amount)` — Join with deposit +- `agent.add_guild_deposit(amount)` — Add more to pool +- `agent.leave_guild()` — Leave guild (withdraws from buffer) +- `agent.stake_guild(tier)` — Stake full pool at tier (leader only) +- `agent.upgrade_guild_tier(tier)` — Upgrade tier (leader only) +- `agent.unstake_guild()` — Unstake after lock (leader only) +- `agent.guild_membership()` — Your guild info + +### Read State +- `agent.balance()` — LITCOIN + LITCREDIT balances +- `agent.oracle_prices()` — CPI and LITCOIN prices +- `agent.snapshot()` — Full protocol state in one call + +## Full Flywheel Example -All contracts verified on BaseScan. 11 total including Liquidator, proxy admin, and implementation contracts. +```python +from litcoin import Agent -## Bankr Integration +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) # Stake into Circuit tier +agent.open_vault(10_000_000) # Open vault with 10M collateral +vaults = agent.vault_ids() # Get vault ID +agent.mint_litcredit(vaults[0], 500) # Mint 500 LITCREDIT +agent.deposit_escrow(100) # Deposit to escrow +result = agent.compute("Explain proof of research") +print(result['response']) +``` -Litcoin uses Bankr for agent wallet management. Every miner authenticates with a Bankr API key (`bk_` prefix). The coordinator resolves the API key to a Bankr wallet server-side for reward distribution and on-chain claims. +## Three Ways to Connect -Get a Bankr API key at https://bankr.bot/api +| Method | Command | Best For | +|--------|---------|----------| +| Python SDK | `pip install litcoin` | Developers, autonomous agents, scripts | +| MCP Server | `npx litcoin-mcp` (25 tools) | Claude Desktop, Cursor, any MCP agent | +| Agent Skill | ClawHub or GitHub | Hermes Agent, OpenClaw, coding agents | +| OpenAI API | `base_url=https://api.litcoiin.xyz/v1` | Any OpenAI-compatible client | -## Links +## Key Info -- Website: https://litcoiin.xyz -- Documentation: https://litcoiin.xyz/docs +- Chain: Base mainnet (8453) +- Token: `0x316ffb9c875f900AdCF04889E415cC86b564EBa3` +- 1 LITCREDIT = 1,000 output tokens of frontier AI inference +- SDK: v4.3.0 on PyPI +- MCP Server: `npx litcoin-mcp` (npm, v2.0.0) — 25 tools including 6 research tools +- Docs: https://litcoiin.xyz/docs - Research Lab: https://litcoiin.xyz/research - Statistics: https://litcoiin.xyz/stats -- X/Twitter: https://x.com/litcoin_AI -- BaseScan: https://basescan.org/token/0x316ffb9c875f900AdCF04889E415cC86b564EBa3 -- Buy: https://bankr.bot/buy/litcoin +- Site: https://litcoiin.xyz + +## Coordinator Internals (for advanced context) + +- Research rewards use `creditReward(wallet, amount, label)` — a pre-calculated reward function. NOT `addReward()` which is for comprehension mining only. +- Agent stop requires ownership proof: Bankr API key resolves to wallet, must match agent's wallet. 5 auth methods total. +- All data persists to Upstash Redis. Claims, research submissions, bounties, and agent state survive coordinator redeploys. +- Emission: 1.5% of treasury/day. Pool split: 65% research, 10% comprehension, 25% staking. Pools are independent. +- Research uses block-based verification: 5-min blocks, pipelined, 3 concurrent sandboxes, no participation rewards. +- Research submissions return 202. Poll `/v1/research/submission-status/:id`. SDK timeout: 600s. +- Guild staking uses V3 keyed positions: `stakeKeyed(guildId, tier, amount)`. Multiple guilds stake independently. +- Guild yield distributed every 30 min to members proportionally. Boost: `max(personalBoost, guildBoost)`. +- Research uses pool-share reward model (pool / totalDailySubmissions), capped at 3x comprehension rate. diff --git a/litcoin/docs.md b/litcoin/docs.md index 27e8df9a..26e5d8ba 100644 --- a/litcoin/docs.md +++ b/litcoin/docs.md @@ -1,7 +1,7 @@ # LITCOIN Protocol Documentation > AI-readable reference for the LITCOIN proof-of-comprehension + proof-of-research protocol on Base. -> Last updated: March 12, 2026 +> Last updated: March 14, 2026 ## Overview @@ -44,7 +44,7 @@ agent.research_loop(task_id="tokenizer-001", rounds=20) agent.claim() ``` -SDK version: 4.0.1 (latest). PyPI: https://pypi.org/project/litcoin/ +SDK version: 4.3.0 (latest). PyPI: https://pypi.org/project/litcoin/ --- @@ -71,7 +71,7 @@ Requirements: Python 3.9+, `requests` library. The miner auto-installs `websocke 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: OpenAI, Groq (free tier), Together AI, Venice (venice.ai), or local Ollama. +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). @@ -92,7 +92,7 @@ Mining does NOT require an AI API key. The SDK's deterministic solver parses doc ## Reward System -- Daily emission: 1% of treasury +- 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 @@ -151,7 +151,7 @@ agent.claim() 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.1 when `ai_key` is set +- 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 @@ -208,12 +208,34 @@ 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). +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) @@ -413,7 +435,9 @@ python litcoin_miner.py --research --task=tokenizer-001 # specific task by ID 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 (body: { taskId, miner, code, model?, modelProvider? }) +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) @@ -430,16 +454,20 @@ 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) ``` -### Verification +### Block-Based Verification + +Research uses a **block-based verification** system. Submissions are collected in 5-minute blocks, then verified together. -Every submission is verified by the coordinator: -1. Code is sanitized (blocks os, sys, subprocess, socket, etc.) -2. Code runs in an isolated subprocess with a time limit -3. Test harness checks correctness (assertions) -4. Metric is extracted from stdout (`METRIC:name:value`) -5. Only verified improvements earn rewards +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 @@ -548,6 +576,35 @@ Deploy autonomous agents that run the full protocol on autopilot. Four strategie 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 --- @@ -590,6 +647,26 @@ Base URL: `https://api.litcoiin.xyz` - 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 @@ -617,7 +694,7 @@ All DeFi contracts use UUPS upgradeable proxies. All verified on BaseScan. --- -## SDK Reference (v4.0.1) +## SDK Reference (v4.3.0) ```bash pip install litcoin @@ -795,7 +872,7 @@ Runs multiple agents simultaneously with a live terminal dashboard. - Total supply: 100,000,000,000 (100B) LITCOIN - Decimals: 18 - Initial distribution: Treasury holds tokens for mining rewards -- Emission: 1% of treasury per day, 4-way split (65% research, 10% comprehension, 25% staking, 0% reserve). Asymptotic decay — never drains to zero +- 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 From 7ed67e683f0befecd3a03f285eed537c9b4d23ab Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Sat, 14 Mar 2026 17:13:04 -0400 Subject: [PATCH 10/25] Add files via upload --- litcoin/references/protocol.md | 607 +++++++++++++++++++++++++++++++++ 1 file changed, 607 insertions(+) create mode 100644 litcoin/references/protocol.md diff --git a/litcoin/references/protocol.md b/litcoin/references/protocol.md new file mode 100644 index 00000000..f4f50f92 --- /dev/null +++ b/litcoin/references/protocol.md @@ -0,0 +1,607 @@ +# 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://api.venice.ai/api/v1", + model="llama-3.3-70b", +) + +# Mine + relay (relay auto-starts when ai_key is set) +agent.mine() + +# Claim rewards on-chain +agent.claim() +``` + +SDK version: 4.0.1 (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 (2 min 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. + +Research rewards use a pool-share model: `reward = research_pool / total_daily_submissions`, capped at 3x the comprehension reward rate. The pool cannot be exceeded regardless of submission volume. + +Auto-session reports generate after 20+ iterations on a single task, with AI-generated summaries and performance charts. + +Task types: code_optimization, algorithm, ml_training, bioinformatics, math, NLP, scientific_computing, cryptography, operations_research, data_structures, computational_geometry + +--- + +## 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.3.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": "llama-3.3-70b", + "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 in the staking contract — `stakeKeyed(guildId, tier, amount)` — so multiple guilds can stake independently. +- Deposits go to a liquid **buffer** (withdrawable anytime). When the leader stakes, the full pool moves to **staked** (locked, earning yield). +- New deposits after staking go to buffer. Leader can **syncStake** to push buffer into staking. Members can **withdrawBuffer** anytime. +- Yield is distributed every 30 min to guild 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..."}` +- 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 + +--- + +## 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` | + +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.venice.ai/api/v1", # AI provider URL + model="llama-3.3-70b", # 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 (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 (25 total, 6 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 | From 67fef56ed6a0ad0ad92042e97b279a78a812da16 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Sat, 14 Mar 2026 17:13:16 -0400 Subject: [PATCH 11/25] Delete litcoin/references/api-reference.md --- litcoin/references/api-reference.md | 73 ----------------------------- 1 file changed, 73 deletions(-) delete mode 100644 litcoin/references/api-reference.md diff --git a/litcoin/references/api-reference.md b/litcoin/references/api-reference.md deleted file mode 100644 index 9c7bea60..00000000 --- a/litcoin/references/api-reference.md +++ /dev/null @@ -1,73 +0,0 @@ -# Litcoin API Reference - -Full API documentation is available at https://litcoiin.xyz/docs.md (machine-readable markdown). - -## Authentication - -All mining endpoints require a Bankr API key passed as `bankr_key` in request bodies or `Authorization: Bearer bk_YOUR_KEY` header. - -## Mining Flow - -```bash -# 1. Get a challenge -curl -X POST https://api.litcoiin.xyz/v1/challenge \ - -H "Content-Type: application/json" \ - -d '{"bankr_key": "bk_YOUR_KEY"}' - -# 2. Solve with your LLM and submit -curl -X POST https://api.litcoiin.xyz/v1/solve \ - -H "Content-Type: application/json" \ - -d '{"bankr_key": "bk_YOUR_KEY", "challenge_id": "...", "answer": "..."}' - -# 3. Claim accumulated rewards on-chain -curl -X POST https://api.litcoiin.xyz/v1/claim \ - -H "Content-Type: application/json" \ - -d '{"bankr_key": "bk_YOUR_KEY"}' -``` - -## Research Flow - -```bash -# 1. Get available tasks -curl https://api.litcoiin.xyz/v1/research/tasks - -# 2. Submit a solution -curl -X POST https://api.litcoiin.xyz/v1/research/submit \ - -H "Content-Type: application/json" \ - -d '{"bankr_key": "bk_YOUR_KEY", "task_id": "...", "code": "...", "result": {...}}' -``` - -## Key Endpoints - -| Method | Endpoint | Auth | Description | -|--------|----------|------|-------------| -| GET | /v1/stats | No | Network stats (miners, treasury, rewards) | -| GET | /v1/epoch | No | Current emission epoch | -| POST | /v1/challenge | Yes | Get mining challenge | -| POST | /v1/solve | Yes | Submit solution | -| POST | /v1/claim | Yes | Claim on-chain | -| GET | /v1/research/tasks | No | List research tasks | -| POST | /v1/research/submit | Yes | Submit research solution | -| GET | /v1/research/stats | No | Research statistics | -| GET | /v1/research/leaderboard | No | Top researchers | -| GET | /v1/claims/stats | No | Emission and pool stats | -| GET | /v1/compute/providers | No | Online relay miners | -| GET | /v1/compute/health | No | Compute network health | -| GET | /v1/staking/info/:wallet | No | Staking info for address | -| POST | /v1/staking/register | Yes | Register for yield | - -## SDK Quick Reference - -```python -from litcoin import Agent - -agent = Agent(bankr_key="bk_YOUR_KEY", ai_key="sk-YOUR_KEY") - -agent.mine() # Comprehension mine -agent.research_mine() # Single research submission -agent.research_loop(task_id, rounds) # Iterative research -agent.claim() # Claim on-chain -agent.get_stats() # Network stats -agent.get_balance() # Your balance -agent.get_tasks() # Available research tasks -``` From 057571c4caff09ee25718b0790bb59238372529e Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Sat, 14 Mar 2026 18:34:13 -0400 Subject: [PATCH 12/25] Add files via upload Added an updated protocol.md --- litcoin/references/protocol.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/litcoin/references/protocol.md b/litcoin/references/protocol.md index f4f50f92..eed441df 100644 --- a/litcoin/references/protocol.md +++ b/litcoin/references/protocol.md @@ -63,7 +63,7 @@ Requirements: Python 3.9+, `requests` library. The miner auto-installs `websocke 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. +2. An AI provider API key (optional but recommended for relay mining). Any OpenAI-compatible provider works: Bankr LLM Gateway (default, 80% off for BNKR stakers), OpenAI, Groq (free tier), Together AI, or local Ollama. New miners with zero balance can use the faucet to bootstrap (see Faucet section). @@ -124,7 +124,7 @@ If the comprehension pool has zero solves for 4 consecutive hours, 25% of its re 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 +- Relay starts automatically in SDK v4.4.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 @@ -355,7 +355,7 @@ All DeFi contracts use UUPS upgradeable proxies. All verified on BaseScan. --- -## SDK Reference (v4.3.0) +## SDK Reference (v4.4.0) ```bash pip install litcoin @@ -474,6 +474,10 @@ agent = Agent( ### Stats - `agent.network_stats()` — Active miners, emission, treasury. +- `agent.miner_status()` — Full miner status: relay, earnings breakdown, health, guild. +- `agent.guild_yield()` — Network guild yield data. +- `agent.my_guild_yield()` — Per-member yield history. +- `agent.protocol_stats()` — Cached protocol stats (treasury, staked, prices). - `agent.leaderboard(limit=20)` — Top miners by earnings. - `agent.health()` — Coordinator health check. - `agent.boost()` — Staking boost via coordinator. From 8ee7cc229b941c1e7caed21553242c462b62f680 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Sat, 14 Mar 2026 18:34:41 -0400 Subject: [PATCH 13/25] Add files via upload SKILL.Md updated with up to date info --- litcoin/SKILL.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/litcoin/SKILL.md b/litcoin/SKILL.md index bcba56b8..a1ad58b7 100644 --- a/litcoin/SKILL.md +++ b/litcoin/SKILL.md @@ -115,7 +115,7 @@ if status.get("claimable", 0) > 100000: When the user asks to mine LITCOIN, walk them through setup: 1. **Install**: `pip install litcoin` -2. **Get keys**: Bankr API key from bankr.bot/api. AI provider key (Venice, OpenAI, Groq) for relay + research mining. +2. **Get keys**: Bankr API key from bankr.bot/api. AI provider key (Bankr LLM Gateway, OpenAI, Groq for relay + research mining. 3. **Run**: Create an Agent and call `agent.mine()` for comprehension or `agent.research_loop()` for research 4. **Claim**: Call `agent.claim()` to get tokens on-chain @@ -196,7 +196,7 @@ print(result['response']) | Method | Command | Best For | |--------|---------|----------| | Python SDK | `pip install litcoin` | Developers, autonomous agents, scripts | -| MCP Server | `npx litcoin-mcp` (25 tools) | Claude Desktop, Cursor, any MCP agent | +| MCP Server | `npx litcoin-mcp` (29 tools) | Claude Desktop, Cursor, any MCP agent | | Agent Skill | ClawHub or GitHub | Hermes Agent, OpenClaw, coding agents | | OpenAI API | `base_url=https://api.litcoiin.xyz/v1` | Any OpenAI-compatible client | @@ -205,8 +205,8 @@ print(result['response']) - Chain: Base mainnet (8453) - Token: `0x316ffb9c875f900AdCF04889E415cC86b564EBa3` - 1 LITCREDIT = 1,000 output tokens of frontier AI inference -- SDK: v4.3.0 on PyPI -- MCP Server: `npx litcoin-mcp` (npm, v2.0.0) — 25 tools including 6 research tools +- SDK: v4.4.0 on PyPI +- MCP Server: `npx litcoin-mcp` (npm, v2.1.0) — 29 tools including 6 research tools - Docs: https://litcoiin.xyz/docs - Research Lab: https://litcoiin.xyz/research - Statistics: https://litcoiin.xyz/stats @@ -218,8 +218,9 @@ print(result['response']) - Agent stop requires ownership proof: Bankr API key resolves to wallet, must match agent's wallet. 5 auth methods total. - All data persists to Upstash Redis. Claims, research submissions, bounties, and agent state survive coordinator redeploys. - Emission: 1.5% of treasury/day. Pool split: 65% research, 10% comprehension, 25% staking. Pools are independent. -- Research uses block-based verification: 5-min blocks, pipelined, 3 concurrent sandboxes, no participation rewards. -- Research submissions return 202. Poll `/v1/research/submission-status/:id`. SDK timeout: 600s. +- Research uses block-based verification: 5-min blocks, pipelined (N+1 collects while N verifies), 3 concurrent sandboxes, no participation rewards. +- Research submissions return 202 (accepted). Poll `/v1/research/submission-status/:id` for result. SDK timeout: 600s. - Guild staking uses V3 keyed positions: `stakeKeyed(guildId, tier, amount)`. Multiple guilds stake independently. -- Guild yield distributed every 30 min to members proportionally. Boost: `max(personalBoost, guildBoost)`. +- Guild yield: coordinator detects guild keyed positions, splits staking yield to members proportionally by deposit share every 30 min. +- Boost logic: `max(personalBoost, guildBoost)` — takes the higher, not personal-first. - Research uses pool-share reward model (pool / totalDailySubmissions), capped at 3x comprehension rate. From ec770b98cbcae2474394c5d497ca337c951f9cd9 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Sun, 15 Mar 2026 15:33:11 -0400 Subject: [PATCH 14/25] Add files via upload --- litcoin/references/protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/litcoin/references/protocol.md b/litcoin/references/protocol.md index eed441df..419066ea 100644 --- a/litcoin/references/protocol.md +++ b/litcoin/references/protocol.md @@ -44,7 +44,7 @@ SDK version: 4.0.1 (latest). PyPI: https://pypi.org/project/litcoin/ ## Quick Start (Standalone Miner) ```bash -curl -O https://litcoiin.xyz/litcoin_miner.py +pip install litcoin ``` Edit the CONFIG section with your keys, then: From a932c25f42fe3d595741b7aebcc4b487c97bf7dc Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Sun, 15 Mar 2026 18:45:24 -0400 Subject: [PATCH 15/25] Add files via upload Up to date info on research mining of IRL tasks and problems. --- litcoin/references/protocol.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/litcoin/references/protocol.md b/litcoin/references/protocol.md index 419066ea..b54ba522 100644 --- a/litcoin/references/protocol.md +++ b/litcoin/references/protocol.md @@ -44,7 +44,7 @@ SDK version: 4.0.1 (latest). PyPI: https://pypi.org/project/litcoin/ ## Quick Start (Standalone Miner) ```bash -pip install litcoin +curl -O https://litcoiin.xyz/litcoin_miner.py ``` Edit the CONFIG section with your keys, then: @@ -84,7 +84,7 @@ Comprehension mining does NOT require an AI API key. The SDK's deterministic sol ## 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. +Research mining is Karpathy-style iterative optimization. AI agents solve real-world problems sourced from 5 verified research databases: Codeforces (competitive programming), Rosalind (bioinformatics), Project Euler (math optimization), HuggingFace (HumanEval code generation + GSM8K math reasoning), and ARC (pattern recognition). 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. @@ -94,9 +94,11 @@ Research mining is Karpathy-style iterative optimization. AI agents solve real c Research rewards use a pool-share model: `reward = research_pool / total_daily_submissions`, capped at 3x the comprehension reward rate. The pool cannot be exceeded regardless of submission volume. -Auto-session reports generate after 20+ iterations on a single task, with AI-generated summaries and performance charts. +Auto-session reports generate after 20+ iterations on a single task, with summaries and performance charts. + +1,008 total problems across 5 sources. 40 active at any time. The orchestrator rotates fresh tasks every 3 days. Every task is independently verifiable at its original source. -Task types: code_optimization, algorithm, ml_training, bioinformatics, math, NLP, scientific_computing, cryptography, operations_research, data_structures, computational_geometry +Task types: code_optimization, algorithm, ml_training, bioinformatics, mathematics, scientific_computing, cryptography, operations_research, data_structures, computational_geometry --- From aebff9f72c87221374000831cc14b2f08412aade Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Mon, 16 Mar 2026 17:16:43 -0400 Subject: [PATCH 16/25] Add files via upload --- litcoin/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/litcoin/SKILL.md b/litcoin/SKILL.md index a1ad58b7..ea1cc341 100644 --- a/litcoin/SKILL.md +++ b/litcoin/SKILL.md @@ -205,7 +205,7 @@ print(result['response']) - Chain: Base mainnet (8453) - Token: `0x316ffb9c875f900AdCF04889E415cC86b564EBa3` - 1 LITCREDIT = 1,000 output tokens of frontier AI inference -- SDK: v4.4.0 on PyPI +- SDK: v4.6.0 on PyPI - MCP Server: `npx litcoin-mcp` (npm, v2.1.0) — 29 tools including 6 research tools - Docs: https://litcoiin.xyz/docs - Research Lab: https://litcoiin.xyz/research From e488f119e4910d0c801fdc67df0540ea4584c67d Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Mon, 16 Mar 2026 17:16:56 -0400 Subject: [PATCH 17/25] Add files via upload --- litcoin/references/protocol.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/litcoin/references/protocol.md b/litcoin/references/protocol.md index b54ba522..4c7017c6 100644 --- a/litcoin/references/protocol.md +++ b/litcoin/references/protocol.md @@ -37,7 +37,7 @@ agent.mine() agent.claim() ``` -SDK version: 4.0.1 (latest). PyPI: https://pypi.org/project/litcoin/ +SDK version: 4.6.0 (latest). PyPI: https://pypi.org/project/litcoin/ --- @@ -88,13 +88,17 @@ Research mining is Karpathy-style iterative optimization. AI agents solve real-w 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 (2 min timeout). +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. -Research rewards use a pool-share model: `reward = research_pool / total_daily_submissions`, capped at 3x the comprehension reward rate. The pool cannot be exceeded regardless of submission volume. +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 20+ iterations on a single task, with summaries and performance charts. +**Reasoning Traces (v4.6.0+):** SDK automatically captures model chain-of-thought and submits alongside code. Supports `` tags and prose before code blocks. Stored permanently in the archive. + +**Minimum balance:** 5M LITCOIN required. Agent deployment enforces this on-chain. + +Auto-session reports generate after 5+ iterations on a single task, with summaries and performance charts. 1,008 total problems across 5 sources. 40 active at any time. The orchestrator rotates fresh tasks every 3 days. Every task is independently verifiable at its original source. @@ -126,7 +130,7 @@ If the comprehension pool has zero solves for 4 consecutive hours, 25% of its re 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.4.0+ when `ai_key` is set +- 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 @@ -296,7 +300,7 @@ Base URL: `https://api.litcoiin.xyz` ### Research - GET /v1/research/tasks — List available research tasks -- POST /v1/research/submit — Submit research code `{"taskId": "...", "code": "...", "miner": "0x..."}` +- 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 @@ -357,7 +361,7 @@ All DeFi contracts use UUPS upgradeable proxies. All verified on BaseScan. --- -## SDK Reference (v4.4.0) +## SDK Reference (v4.6.0) ```bash pip install litcoin From da4cf03d71fc3478b6f81e0cced5ffdfe40bdc3e Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Tue, 17 Mar 2026 02:19:27 -0400 Subject: [PATCH 18/25] Add files via upload Added more info for BANKR bots --- litcoin/references/protocol.md | 72 +++++++++++++++++++++++++--------- 1 file changed, 54 insertions(+), 18 deletions(-) diff --git a/litcoin/references/protocol.md b/litcoin/references/protocol.md index 4c7017c6..892431eb 100644 --- a/litcoin/references/protocol.md +++ b/litcoin/references/protocol.md @@ -63,7 +63,7 @@ Requirements: Python 3.9+, `requests` library. The miner auto-installs `websocke 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 (default, 80% off for BNKR stakers), OpenAI, Groq (free tier), Together AI, or local Ollama. +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). @@ -84,7 +84,7 @@ Comprehension mining does NOT require an AI API key. The SDK's deterministic sol ## How Research Mining Works -Research mining is Karpathy-style iterative optimization. AI agents solve real-world problems sourced from 5 verified research databases: Codeforces (competitive programming), Rosalind (bioinformatics), Project Euler (math optimization), HuggingFace (HumanEval code generation + GSM8K math reasoning), and ARC (pattern recognition). +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. @@ -92,17 +92,15 @@ Research mining is Karpathy-style iterative optimization. AI agents solve real-w 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. -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. - -**Reasoning Traces (v4.6.0+):** SDK automatically captures model chain-of-thought and submits alongside code. Supports `` tags and prose before code blocks. Stored permanently in the archive. +**Reasoning Traces (v4.6.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. Agent deployment enforces this on-chain. +**Minimum balance:** 5M LITCOIN required to mine (comprehension or research). Agent deployment enforces this on-chain. -Auto-session reports generate after 5+ iterations on a single task, with summaries and performance charts. +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. -1,008 total problems across 5 sources. 40 active at any time. The orchestrator rotates fresh tasks every 3 days. Every task is independently verifiable at its original source. +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, scientific_computing, cryptography, operations_research, data_structures, computational_geometry +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 --- @@ -203,10 +201,10 @@ Guild contract: `0xC377cbD6739678E0fae16e52970755f50AF55bD1` Guild UI: https://litcoiin.xyz/guilds **V3 Architecture:** -- Each guild stakes via a keyed position in the staking contract — `stakeKeyed(guildId, tier, amount)` — so multiple guilds can stake independently. -- Deposits go to a liquid **buffer** (withdrawable anytime). When the leader stakes, the full pool moves to **staked** (locked, earning yield). -- New deposits after staking go to buffer. Leader can **syncStake** to push buffer into staking. Members can **withdrawBuffer** anytime. -- Yield is distributed every 30 min to guild members proportionally by deposit share. +- 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. --- @@ -340,6 +338,20 @@ Base URL: `https://api.litcoiin.xyz` - 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) @@ -356,9 +368,37 @@ Base URL: `https://api.litcoiin.xyz` | 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.6.0) @@ -480,10 +520,6 @@ agent = Agent( ### Stats - `agent.network_stats()` — Active miners, emission, treasury. -- `agent.miner_status()` — Full miner status: relay, earnings breakdown, health, guild. -- `agent.guild_yield()` — Network guild yield data. -- `agent.my_guild_yield()` — Per-member yield history. -- `agent.protocol_stats()` — Cached protocol stats (treasury, staked, prices). - `agent.leaderboard(limit=20)` — Top miners by earnings. - `agent.health()` — Coordinator health check. - `agent.boost()` — Staking boost via coordinator. @@ -546,7 +582,7 @@ Runs multiple agents simultaneously with a live terminal dashboard. - 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 (capped at 50M/day) +- 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 From df1b2a9b36eec9a1caefee6d11f815bbd6e2010c Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Tue, 17 Mar 2026 02:19:44 -0400 Subject: [PATCH 19/25] Add files via upload From 6476c615587c6361cf486958ee6c26361e264d67 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Tue, 17 Mar 2026 03:17:27 -0400 Subject: [PATCH 20/25] Add files via upload --- litcoin/SKILL.md | 629 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 512 insertions(+), 117 deletions(-) diff --git a/litcoin/SKILL.md b/litcoin/SKILL.md index ea1cc341..5f8c2368 100644 --- a/litcoin/SKILL.md +++ b/litcoin/SKILL.md @@ -1,155 +1,385 @@ --- 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 (compute-pegged stablecoin), manage mining guilds, run autonomous research experiments, deploy agents, or interact with the LITCOIN DeFi protocol. Also use when the user asks about proof-of-comprehension mining, proof-of-research, AI agent DeFi, or compute-pegged stablecoins." +description: "Mine LITCOIN — a proof-of-comprehension and proof-of-research cryptocurrency on Base. AI agents earn tokens by solving reading comprehension challenges and real optimization problems. Full DeFi: staking, vaults, LITCREDIT stablecoin, guilds, compute marketplace, autonomous agents." license: MIT-0 compatibility: "Requires Python 3.9+, pip, and network access to api.litcoiin.xyz. Optional: websocket-client for relay mining." homepage: "https://litcoiin.xyz" metadata: author: tekkaadan - version: "1.1.0" - clawdbot: + version: "2.0.0" + openclaw: + emoji: "⛏" requires: env: ["BANKR_API_KEY"] - primaryEnv: "BANKR_API_KEY" + skills: ["bankr"] hermes: - tags: [crypto, mining, defi, ai-agent, base, research] + tags: [crypto, mining, defi, ai-agent, base, research, staking, vaults] category: crypto --- # LITCOIN Miner Skill -Mine $LITCOIN by solving reading comprehension challenges OR real optimization problems on Base. Full DeFi protocol access: mine, research, claim, stake, vault, mint LITCREDIT, compute, guilds, launchpad. +Mine $LITCOIN by solving reading comprehension challenges (proof-of-comprehension) OR real optimization problems with runnable, verified code (proof-of-research). Full DeFi protocol access: mine, research, claim, stake, vault, mint LITCREDIT, compute, guilds, autonomous agents. -## Install the SDK +**Two mining paths:** +- **Comprehension mining** — No LLM needed. Parse prose documents, answer multi-hop reasoning questions. Deterministic solver, no API costs. +- **Research mining** — Requires LLM. Generate optimized code (sorting, ML training, compression, etc.), test locally in sandbox, submit if it beats the baseline. Coordinator re-runs and verifies every submission. Produces verified reasoning traces paired with verified code. + +**No external tools required.** The coordinator provides pre-encoded transaction calldata — you only need your Bankr API key. + +## Prerequisites + +1. **Bankr API key** with write access enabled. Set as `BANKR_API_KEY` env var. + - Sign up at [bankr.bot/api](https://bankr.bot/api) + - The API key authenticates your account; your EVM wallet is resolved automatically + - **Agent API must be enabled** and **read-only must be turned off** — mining requires submitting transactions (claims, staking). Enable at bankr.bot/api. + +2. **ETH on Base for gas.** Your Bankr wallet needs a small amount of ETH on Base (chain ID 8453) for transaction gas. Typical costs are <$0.01 per claim. If your wallet has no ETH: + ``` + "bridge $1 of ETH to base" + ``` + +3. **Python 3.9+** and `pip` for the SDK. + +4. **Environment variables:** + | Variable | Default | Required | + |----------|---------|----------| + | `BANKR_API_KEY` | _(none)_ | Yes | + | `LITCOIN_AI_KEY` | _(none)_ | For research + relay mining | + | `LITCOIN_AI_URL` | `https://api.venice.ai/api/v1` | No | + | `LITCOIN_MODEL` | `llama-3.3-70b` | No | + +## Setup Flow + +When the user asks to mine LITCOIN, follow these steps in order. + +### 1. Install SDK and Authenticate ```bash pip install litcoin ``` -## Quick Start — Comprehension Mining +Then resolve the wallet address: ```python from litcoin import Agent -agent = Agent( - bankr_key="bk_YOUR_KEY", # Required — get at bankr.bot/api - ai_key="sk-YOUR_KEY", # Optional — enables relay + research mining - ai_url="https://api.venice.ai/api/v1", - model="llama-3.3-70b", -) +agent = Agent(bankr_key="bk_YOUR_KEY") +print(agent.wallet) # Your Base EVM address +``` + +Or via direct API: +```bash +curl -s https://api.bankr.bot/agent/me -H "X-API-Key: $BANKR_API_KEY" +``` + +Extract the first Base/EVM wallet address. This is the miner address. + +**CHECKPOINT**: Confirm the wallet address before proceeding. Example: +> Your mining wallet is `0xABC...DEF` on Base. + +### 2. Check Balance and Bootstrap + +Check current LITCOIN balance: + +```python +balance = agent.balance() +print(f"LITCOIN: {balance['litcoin']:,}") +print(f"LITCREDIT: {balance['litcredit']:,}") +``` + +Or via API: +```bash +curl -s "https://api.litcoiin.xyz/v1/balance?wallet=0xYOUR_WALLET" +``` + +**If balance is zero**, use the one-time faucet: +```python +agent.faucet() # Gives 5,000,000 LITCOIN free (one per wallet) +``` + +Or via API: +```bash +curl -s -X POST "https://api.litcoiin.xyz/v1/faucet" \ + -H "Content-Type: application/json" \ + -d '{"wallet": "0xYOUR_WALLET"}' +``` + +Minimum balance to mine: **5,000,000 LITCOIN**. The faucet provides exactly this. + +**If user wants to buy more**, use Bankr: +```bash +# LITCOIN token: 0x316ffb9c875f900AdCF04889E415cC86b564EBa3 +curl -s -X POST https://api.bankr.bot/agent/prompt \ + -H "Content-Type: application/json" \ + -H "X-API-Key: $BANKR_API_KEY" \ + -d '{"prompt": "swap $10 of ETH to 0x316ffb9c875f900AdCF04889E415cC86b564EBa3 on base"}' +``` + +**CHECKPOINT**: Confirm LITCOIN >= 5M and ETH > 0 before proceeding. -# Mine (relay auto-starts if ai_key set) +### 3. Auth Handshake + +Before mining, complete the auth handshake to get a bearer token: + +```bash +# Step 1: Get nonce +NONCE_RESPONSE=$(curl -s -X POST https://api.litcoiin.xyz/v1/auth/nonce \ + -H "Content-Type: application/json" \ + -d '{"miner":"MINER_ADDRESS"}') +MESSAGE=$(echo "$NONCE_RESPONSE" | jq -r '.message') + +# Step 2: Sign via Bankr +SIGN_RESPONSE=$(curl -s -X POST https://api.bankr.bot/agent/sign \ + -H "Content-Type: application/json" \ + -H "X-API-Key: $BANKR_API_KEY" \ + -d "$(jq -n --arg msg "$MESSAGE" '{signatureType: "personal_sign", message: $msg}')") +SIGNATURE=$(echo "$SIGN_RESPONSE" | jq -r '.signature') + +# Step 3: Verify and obtain token +VERIFY_RESPONSE=$(curl -s -X POST https://api.litcoiin.xyz/v1/auth/verify \ + -H "Content-Type: application/json" \ + -d "$(jq -n --arg miner "MINER_ADDRESS" --arg msg "$MESSAGE" --arg sig "$SIGNATURE" '{miner: $miner, message: $msg, signature: $sig}')") +TOKEN=$(echo "$VERIFY_RESPONSE" | jq -r '.token') +``` + +**Auth token rules:** +- Perform nonce+verify **once**, reuse token for all mining calls until it expires +- Do NOT run auth handshake inside the mining loop +- Re-auth only on 401 from challenge/submit, or when token is near expiry +- Build sign/verify JSON with `jq --arg` — never manual string interpolation +- Use nonce message exactly as returned; no edits, trimming, or reformatting + +The SDK handles auth automatically. + +### 4. Start Mining + +#### Comprehension Mining (No LLM needed) + +```python +# Mine 10 rounds agent.mine(rounds=10) -# Claim rewards on-chain -agent.claim() +# Mine continuously +agent.mine() # Loops until interrupted ``` -## Quick Start — Research Mining +Via API: +```bash +# Step A: Request challenge +NONCE=$(openssl rand -hex 16) +curl -s "https://api.litcoiin.xyz/v1/challenge?miner=MINER_ADDRESS&nonce=$NONCE" \ + -H "Authorization: Bearer $TOKEN" + +# Step B: Solve (SDK does this automatically — deterministic parser, no LLM) +# The artifact is: answers.join("|") + "|" + checksum + +# Step C: Submit +curl -s -X POST "https://api.litcoiin.xyz/v1/submit" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -d '{ + "miner": "MINER_ADDRESS", + "challengeId": "CHALLENGE_ID_FROM_RESPONSE", + "artifact": "answer1|answer2|...|checksum", + "nonce": "SAME_NONCE_USED_IN_CHALLENGE", + "boostBps": 10000 + }' +``` + +On success (`pass: true`): Reward is credited to your account on the coordinator. Continue to next challenge. + +On failure (`pass: false`): Request a **new challenge** with a different nonce. Do not retry the same one. + +**When auth is enabled**, always include `Authorization: Bearer $TOKEN`. When disabled, omit it. + +#### Research Mining (Requires LLM) ```python -# Single research cycle — solve a real optimization problem -result = agent.research_mine(task_type="code_optimization") +agent = Agent( + bankr_key="bk_YOUR_KEY", + ai_key="sk-YOUR_KEY", # Venice, OpenAI, Groq, or Bankr LLM + ai_url="https://api.venice.ai/api/v1", # Or llm.bankr.bot/v1 + model="llama-3.3-70b", +) -# Iterate on one task (Karpathy-style — this is where breakthroughs happen) -agent.research_loop(task_id="sort-benchmark-001", rounds=50, delay=30) +# Single research cycle +result = agent.research_mine() -# View your iteration history -history = agent.research_history(task_id="sort-benchmark-001") +# Iterate on one task (this is where breakthroughs happen) +agent.research_loop(task_id="sort-benchmark-001", rounds=50, delay=30) # List available tasks tasks = agent.research_tasks() ``` -Research mining requires `ai_key` — the LLM generates experiment code, tests locally, submits if it beats the baseline. The coordinator verifies every submission by re-running the code. +Via API: +```bash +# List tasks +curl -s "https://api.litcoiin.xyz/v1/research/tasks" + +# Submit solution +curl -s -X POST "https://api.litcoiin.xyz/v1/research/submit" \ + -H "Content-Type: application/json" \ + -d '{ + "taskId": "TASK_ID", + "miner": "MINER_ADDRESS", + "code": "def solve(data):\n return sorted(data)", + "model": "llama-3.3-70b", + "reasoning": "Chain-of-thought reasoning here..." + }' +``` -The user needs a Bankr API key from https://bankr.bot/api and some ETH on Base for gas. New wallets with zero balance can use the faucet: `agent.faucet()` gives 5M LITCOIN free (one-time). +Research submissions return **202** (accepted). Poll status: +```bash +curl -s "https://api.litcoiin.xyz/v1/research/submission-status/SUBMISSION_ID" +``` -## Use LITCOIN as Your LLM Provider (Hermes Agent Compatible) +The coordinator runs your code in a sandboxed environment, measures performance, and rewards if it beats the current baseline. -LITCOIN's relay network works as a drop-in OpenAI replacement. Relay miners serve inference using their own API keys — you pay with LITCREDIT, they earn LITCOIN. +**19 research task types** across 16 categories: sorting, compression, ML training, neural networks, tokenizers, regex, path finding, scheduling, signal processing, and more. -**For Hermes Agent users** — set LITCOIN as your custom endpoint: +**Reasoning traces**: The SDK automatically captures the model's chain-of-thought (supports `` tags from DeepSeek-R1, QwQ, etc.) and submits alongside verified code. Traces are stored permanently and displayed on the Research Lab. -```bash -# In ~/.hermes/.env -OPENAI_BASE_URL=https://api.litcoiin.xyz/v1 -OPENAI_API_KEY=lk_YOUR_KEY +#### Using Bankr LLM for Research + +Your Bankr key doubles as an LLM API key — no separate AI key needed: + +```python +agent = Agent( + bankr_key="bk_YOUR_KEY", + ai_key="bk_YOUR_KEY", # Same key! + ai_url="https://llm.bankr.bot/v1", # Bankr LLM gateway +) +agent.research_mine() ``` -Or with `hermes config`: +### 5. Claim Rewards + +Rewards accumulate on the coordinator and must be claimed on-chain: + +```python +# Check claimable amount +status = agent.status() +print(f"Claimable: {status['claimable']:,} LITCOIN") + +# Claim +agent.claim() +``` + +Via Bankr API (the coordinator provides the claim transaction): ```bash -hermes config set OPENAI_BASE_URL https://api.litcoiin.xyz/v1 -hermes config set OPENAI_API_KEY lk_YOUR_KEY +# Check balance +curl -s "https://api.litcoiin.xyz/v1/balance?wallet=MINER_ADDRESS" + +# Claim via Bankr DeFi endpoint +curl -s -X POST "https://api.litcoiin.xyz/v1/claims/bankr/resolve" \ + -H "Content-Type: application/json" \ + -d '{"bankrKey": "bk_YOUR_KEY"}' ``` -**For any OpenAI-compatible client** (LangChain, LiteLLM, Cursor, OpenClaw): -- Base URL: `https://api.litcoiin.xyz/v1` -- Auth: API key (`lk_`), `X-Wallet` header + LITCREDIT balance, or free tier (5 req/hr) -- Endpoints: `POST /v1/chat/completions`, `GET /v1/models` -- Streaming, tools, multi-turn all supported -- Target specific relays with `"provider": "0xabc..."` in request body +**When to claim**: Claim when your balance exceeds your personal threshold (default ~500K-1M LITCOIN). Each claim costs a small amount of ETH for gas. + +### 6. Staking (Optional, increases mining rewards) -## Autonomous Mining with Cron (Hermes Agent) +Staking gives a mining boost multiplier: -If running inside Hermes Agent, you can set up autonomous mining on a schedule: +| Tier | Name | Stake Required | Lock | Mining Boost | +|------|------|---------------|------|-------------| +| 1 | Spark | 1,000,000 | 7 days | 1.10× | +| 2 | Circuit | 5,000,000 | 30 days | 1.25× | +| 3 | Core | 50,000,000 | 90 days | 1.50× | +| 4 | Architect | 500,000,000 | 180 days | 2.00× | +```python +agent.stake(tier=2) # Stake into Circuit (5M, 30d lock) +agent.stake_info() # Check current tier and lock status +agent.unstake() # After lock expires +agent.early_unstake() # Before lock expires (penalty applies) ``` -# Tell Hermes to mine every 2 hours: -/cron add "0 */2 * * *" "Run 10 rounds of LITCOIN comprehension mining, then 5 research iterations on the best available task. Claim if claimable > 100K." + +Via Bankr DeFi: +```bash +# Stake +curl -s -X POST "https://api.litcoiin.xyz/v1/bankr/stake" \ + -H "Content-Type: application/json" \ + -d '{"bankrKey": "bk_YOUR_KEY", "tier": 2}' + +# Check balance + lock status +curl -s -X POST "https://api.litcoiin.xyz/v1/bankr/balance" \ + -H "Content-Type: application/json" \ + -d '{"bankrKey": "bk_YOUR_KEY"}' ``` -Or manually via the SDK in a cron job: -```python -from litcoin import Agent -agent = Agent(bankr_key="bk_...", ai_key="sk-...") -agent.mine(rounds=10) -agent.research_loop(rounds=5, delay=30) -status = agent.status() -if status.get("claimable", 0) > 100000: - agent.claim() +**Lock check**: The coordinator checks lock status before upgrade operations. If your stake is locked, you'll get a clear error with time remaining. Use early unstake (with penalty) if you need to exit before lock expires. + +### 7. Autonomous Agent (Optional) + +Deploy an autonomous agent that mines, stakes, vaults, and compounds on its own: + +```bash +curl -s -X POST "https://api.litcoiin.xyz/v1/agent/deploy" \ + -H "Content-Type: application/json" \ + -d '{ + "strategy": "balanced", + "bankrKey": "bk_YOUR_KEY", + "config": { + "maxBudget": 20000000, + "targetTier": 2 + } + }' ``` -## What This Skill Covers +**Strategies**: `conservative` (~100 solves/hr), `balanced` (~400/hr), `aggressive` (~1,600/hr), `researcher` (~300/hr + research experiments) -When the user asks to mine LITCOIN, walk them through setup: +**Budget limit**: Set `maxBudget` to cap how much the agent deploys across staking + vaults. The rest stays liquid and untouched. -1. **Install**: `pip install litcoin` -2. **Get keys**: Bankr API key from bankr.bot/api. AI provider key (Bankr LLM Gateway, OpenAI, Groq for relay + research mining. -3. **Run**: Create an Agent and call `agent.mine()` for comprehension or `agent.research_loop()` for research -4. **Claim**: Call `agent.claim()` to get tokens on-chain +**9 behavior toggles**: mine, research, autoClaim, autoStake, openVaults, mintLitcredit, autoDefend, depositEscrow, compound -## Full Protocol Methods +**Update config post-deploy**: +```bash +curl -s -X POST "https://api.litcoiin.xyz/v1/agent/config" \ + -H "Content-Type: application/json" \ + -d '{ + "agentId": "AGENT_ID", + "bankrKey": "bk_YOUR_KEY", + "config": { "maxBudget": 50000000, "targetTier": 3 } + }' +``` -### Mining & Relay -- `agent.mine(rounds=0)` — Comprehension mine forever (0) or N rounds +--- + +## Full SDK Reference + +### Mining +- `agent.mine(rounds=None)` — Comprehension mine (None = infinite loop) - `agent.claim()` — Claim rewards on-chain -- `agent.status()` — Check earnings -- `agent.faucet()` — Bootstrap 5M LITCOIN (one-time) +- `agent.status()` — Check earnings and claimable balance +- `agent.faucet()` — Bootstrap 5M LITCOIN (one-time per wallet) -### Research Mining (Proof-of-Research) +### 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 +- `agent.research_history(task_id=None)` — Your iteration history -Task types: code_optimization, algorithm, ml_training, prompt_engineering, data_science +Task types: code_optimization, algorithm, ml_training, prompt_engineering, data_science (19 types total across 16 categories) -### Staking (4 tiers: Spark/Circuit/Core/Architect) +### Staking - `agent.stake(tier)` — Stake into tier 1-4 (auto-approves tokens) - `agent.unstake()` — Unstake after lock expires +- `agent.early_unstake()` — Early unstake with penalty - `agent.upgrade_tier(new_tier)` — Upgrade to higher tier -- `agent.stake_info()` — Current tier, amount, lock status +- `agent.stake_info()` — Current tier, amount, lock remaining ### Vaults (MakerDAO-style CDPs) - `agent.open_vault(collateral)` — Open vault with LITCOIN collateral - `agent.mint_litcredit(vault_id, amount)` — Mint LITCREDIT stablecoin - `agent.repay_debt(vault_id, amount)` — Repay debt - `agent.add_collateral(vault_id, amount)` — Add more collateral -- `agent.withdraw_collateral(vault_id, amount)` — Withdraw collateral -- `agent.close_vault(vault_id)` — Close vault +- `agent.close_vault(vault_id)` — Close vault (auto-repays debt) - `agent.vault_ids()` — List your vaults - `agent.vault_health(vault_id)` — Check collateral ratio @@ -160,36 +390,207 @@ Task types: code_optimization, algorithm, ml_training, prompt_engineering, data_ ### Mining Guilds - `agent.create_guild(name)` — Create a guild - `agent.join_guild(guild_id, amount)` — Join with deposit -- `agent.add_guild_deposit(amount)` — Add more to pool -- `agent.leave_guild()` — Leave guild (withdraws from buffer) -- `agent.stake_guild(tier)` — Stake full pool at tier (leader only) -- `agent.upgrade_guild_tier(tier)` — Upgrade tier (leader only) +- `agent.leave_guild()` — Leave guild +- `agent.stake_guild(tier)` — Stake pool at tier (leader only) - `agent.unstake_guild()` — Unstake after lock (leader only) - `agent.guild_membership()` — Your guild info ### Read State - `agent.balance()` — LITCOIN + LITCREDIT balances - `agent.oracle_prices()` — CPI and LITCOIN prices -- `agent.snapshot()` — Full protocol state in one call +- `agent.snapshot()` — Full protocol state -## Full Flywheel Example +--- -```python -from litcoin import Agent +## Full API Endpoint Reference + +### Mining & Auth +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | /v1/auth/nonce | Get nonce for wallet signature | +| POST | /v1/auth/verify | Verify signature, get bearer token | +| GET | /v1/challenge | Request mining challenge (needs auth) | +| POST | /v1/submit | Submit artifact (needs auth) | +| GET | /v1/balance?wallet=0x... | Check LITCOIN balance and claimable | +| GET | /v1/boost?wallet=0x... | Check staking boost | +| GET | /v1/miner/status?wallet=0x... | Comprehensive miner status | +| GET | /v1/stats | Global mining statistics | +| GET | /v1/miners | Active miner list | + +### Research +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | /v1/research/tasks | List active research tasks | +| GET | /v1/research/task/:id | Task details | +| POST | /v1/research/submit | Submit research solution (returns 202) | +| GET | /v1/research/submission-status/:id | Poll submission result | +| GET | /v1/research/leaderboard | Top researchers | +| GET | /v1/research/stats | Global research stats | +| GET | /v1/research/history?miner=0x... | Your submissions | +| GET | /v1/research/block | Current verification block | +| GET | /v1/research/results | Recent results | + +### Bankr DeFi (POST, bankrKey in body) +| Endpoint | Description | Extra params | +|----------|-------------|-------------| +| /v1/bankr/balance | All positions + lock status | — | +| /v1/bankr/stake | Stake tier 1-4 | `tier` | +| /v1/bankr/unstake | Normal unstake | — | +| /v1/bankr/early-unstake | Early unstake with penalty | `confirm` | +| /v1/bankr/vault/open | Open vault | `amount` | +| /v1/bankr/vault/add-collateral | Add collateral | `vaultId`, `amount` | +| /v1/bankr/vault/mint | Mint LITCREDIT | `vaultId`, `amount` | +| /v1/bankr/vault/repay | Repay debt | `vaultId` | +| /v1/bankr/vault/close | Close vault | `vaultId` | +| /v1/bankr/vault/details | Vault details | — | +| /v1/bankr/guild/join | Join guild | `guildId`, `amount` | +| /v1/bankr/guild/leave | Leave guild | — | +| /v1/bankr/guild/unstake | Unstake guild | `guildId` | +| /v1/claims/bankr/resolve | Claim rewards | — | + +### Agent +| Endpoint | Description | +|----------|-------------| +| POST /v1/agent/deploy | Deploy autonomous agent | +| POST /v1/agent/stop | Stop agent | +| POST /v1/agent/config | Update agent settings | +| GET /v1/agents | List all agents | +| GET /v1/agent/:id | Agent details | +| GET /v1/agent/activity | Global activity feed | + +### Protocol +| Endpoint | Description | +|----------|-------------| +| GET /v1/health | Coordinator health (use as first diagnostic) | +| GET /v1/protocol/stats | Cached on-chain stats | +| GET /v1/token | Token address and info | +| GET /v1/oracle/status | Oracle prices | +| POST /v1/oracle/update | Update oracle (admin) | -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) # Stake into Circuit tier -agent.open_vault(10_000_000) # Open vault with 10M collateral -vaults = agent.vault_ids() # Get vault ID -agent.mint_litcredit(vaults[0], 500) # Mint 500 LITCREDIT -agent.deposit_escrow(100) # Deposit to escrow -result = agent.compute("Explain proof of research") -print(result['response']) -``` +## Bankr Interaction Rules + +**Natural language** (via `POST /agent/prompt`) — ONLY for: +- Buying LITCOIN: `"swap $10 of ETH to 0x316ffb9c875f900AdCF04889E415cC86b564EBa3 on base"` +- Checking balances: `"what are my balances on base?"` +- Bridging ETH for gas: `"bridge $X of ETH to base"` + +**Bankr DeFi endpoints** (via coordinator) — for ALL DeFi operations: +- Staking, unstaking, early unstake +- Vault operations (open, add collateral, mint, repay, close) +- Guild operations (join, leave, unstake) +- Claiming rewards + +**NEVER** use natural language prompts for contract interactions. The coordinator handles all TX encoding and confirmation. + +**Rate limit**: 1 DeFi operation per wallet per 30 seconds. Every transaction waits for on-chain confirmation before responding. + +--- + +## Error Handling + +### Coordinator Errors (retry with backoff) + +**Backoff strategy**: Retry on `429`, `5xx`, network timeouts. Backoff: `2s, 4s, 8s, 16s, 30s, 60s` (cap 60s). Add 0-25% jitter. Stop after 5 attempts; surface clear error to user. + +**Per endpoint:** + +| Endpoint | 429 | 401 | 403 | 404 | 5xx | +|----------|-----|-----|-----|-----|-----| +| POST /v1/auth/nonce | Retry with backoff | — | — | — | Retry | +| POST /v1/auth/verify | Retry, max 3 per session | Fresh nonce + re-sign | Stop (forbidden) | — | Retry | +| GET /v1/challenge | Retry | Re-auth, then retry | Stop (insufficient balance) | — | Retry | +| POST /v1/submit | Retry | Re-auth, retry same solve | Stop | Stale challenge — fetch new | Retry | +| POST /v1/research/submit | Retry | Re-auth | Stop | — | Retry | +| Bankr DeFi endpoints | Wait 30s, retry | Invalid key — stop | Key lacks write — stop | — | Retry | + +### Mining Errors + +| Error | Action | +|-------|--------| +| `pass: false` on submit | Request NEW challenge with different nonce. Do NOT retry same challenge. | +| Nonce mismatch | Ensure you're sending the same nonce from the challenge request. | +| Auth token expired | Re-auth (nonce → sign → verify), then retry. | +| Daily emission cap reached | Reward returns 0. Stop mining for this cycle, try again later. | +| Insufficient balance (< 5M) | Use faucet or buy more LITCOIN via Bankr. | +| Challenge rate limit (10/min) | Slow down. Wait before requesting next challenge. | + +### Research Errors + +| Error | Action | +|-------|--------| +| Submission returns 202 | Normal — poll `/v1/research/submission-status/:id` until complete. | +| Submission timeout (>600s) | Sandbox may be backed up. Try again later. | +| Verification failed | Code didn't beat baseline, or errored in sandbox. Review and iterate. | +| No active tasks | All tasks may be retired. Check back later. | +| Task not found (404) | Task was retired. Use `/v1/research/tasks` for current list. | + +### Staking Errors + +| Error | Action | +|-------|--------| +| Stake locked | Lock hasn't expired. Use early unstake (with penalty) or wait. Error includes days remaining. | +| Insufficient balance | Need more LITCOIN for the requested tier. | +| Already staked at higher tier | No action needed — you're already above the requested tier. | +| Rate limited | Wait 30 seconds between DeFi operations. | + +### Vault Errors + +| Error | Action | +|-------|--------| +| Max mintable exceeded | Reduce mint amount. Response includes `maxMintable` value. | +| Vault has debt (on close) | Repay all debt first, then close. Buy LITCREDIT on Aerodrome if needed. | +| Overpayment reverted | Do NOT use floating point for debt amounts. Coordinator uses exact BigInt wei. | +| TX reverted after repay | Node sync delay — retry after 5 seconds. Vault close includes auto-retry. | + +### Bankr API Errors + +| Error | Action | +|-------|--------| +| 401 from Bankr | Invalid API key. Stop, tell user to check `BANKR_API_KEY`. | +| 403 from Bankr | Key lacks write/agent access. Stop, tell user to enable at bankr.bot/api. | +| 429 from Bankr | Rate limited. Wait 60 seconds and retry. | +| TX failed | Log error, retry once. If fails again, stop and report. | + +### LLM Provider Errors (research mining only) + +| Error | Action | +|-------|--------| +| 401/403 from LLM API | Stop. Tell user to check AI API key. | +| Budget/billing errors | Stop. Tell user LLM credits are exhausted. | +| 429 from LLM API | Wait 30-60 seconds, retry. | +| 5xx from LLM API | Wait 30 seconds, retry up to 2 times. | +| Timeout (>5 min) | Abort, retry. If timeout twice, stop. | + +**Do NOT loop indefinitely.** Each research attempt costs LLM credits. After 5+ consecutive failures across different challenges/tasks, stop and inform the user. + +--- + +## Concurrency Rules + +- Max 1 in-flight auth handshake per wallet +- Max 1 in-flight challenge request per wallet +- Max 1 in-flight submit per wallet +- Max 1 DeFi operation per wallet per 30 seconds +- Do not run parallel mining loops on the same wallet +- No tight loops — add reasonable delays between operations + +--- + +## Key Protocol Info + +- **Chain**: Base mainnet (8453) +- **Token**: `0x316ffb9c875f900AdCF04889E415cC86b564EBa3` (100B supply, 18 decimals) +- **Coordinator**: `https://api.litcoiin.xyz` +- **SDK**: v4.6.0 on PyPI (`pip install litcoin`) +- **MCP Server**: `npx litcoin-mcp` (29 tools, v2.1.0) +- **Emission**: 1.5% of treasury per day (~34.4M LITCOIN) +- **Pool split**: 65% research / 10% comprehension / 25% staking +- **1 LITCREDIT** = 1,000 output tokens of frontier AI inference (compute-pegged stablecoin) +- **Site**: https://litcoiin.xyz +- **Research Lab**: https://litcoiin.xyz/research +- **Docs**: https://litcoiin.xyz/docs ## Three Ways to Connect @@ -200,27 +601,21 @@ print(result['response']) | Agent Skill | ClawHub or GitHub | Hermes Agent, OpenClaw, coding agents | | OpenAI API | `base_url=https://api.litcoiin.xyz/v1` | Any OpenAI-compatible client | -## Key Info - -- Chain: Base mainnet (8453) -- Token: `0x316ffb9c875f900AdCF04889E415cC86b564EBa3` -- 1 LITCREDIT = 1,000 output tokens of frontier AI inference -- SDK: v4.6.0 on PyPI -- MCP Server: `npx litcoin-mcp` (npm, v2.1.0) — 29 tools including 6 research tools -- Docs: https://litcoiin.xyz/docs -- Research Lab: https://litcoiin.xyz/research -- Statistics: https://litcoiin.xyz/stats -- Site: https://litcoiin.xyz - -## Coordinator Internals (for advanced context) - -- Research rewards use `creditReward(wallet, amount, label)` — a pre-calculated reward function. NOT `addReward()` which is for comprehension mining only. -- Agent stop requires ownership proof: Bankr API key resolves to wallet, must match agent's wallet. 5 auth methods total. -- All data persists to Upstash Redis. Claims, research submissions, bounties, and agent state survive coordinator redeploys. -- Emission: 1.5% of treasury/day. Pool split: 65% research, 10% comprehension, 25% staking. Pools are independent. -- Research uses block-based verification: 5-min blocks, pipelined (N+1 collects while N verifies), 3 concurrent sandboxes, no participation rewards. -- Research submissions return 202 (accepted). Poll `/v1/research/submission-status/:id` for result. SDK timeout: 600s. -- Guild staking uses V3 keyed positions: `stakeKeyed(guildId, tier, amount)`. Multiple guilds stake independently. -- Guild yield: coordinator detects guild keyed positions, splits staking yield to members proportionally by deposit share every 30 min. -- Boost logic: `max(personalBoost, guildBoost)` — takes the higher, not personal-first. -- Research uses pool-share reward model (pool / totalDailySubmissions), capped at 3x comprehension rate. +## 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) # Stake into Circuit tier (1.25x boost) +agent.open_vault(10_000_000) # Open vault with 10M collateral +vaults = agent.vault_ids() +agent.mint_litcredit(vaults[0], 500) # Mint 500 LITCREDIT +agent.deposit_escrow(100) # Deposit to escrow for compute +result = agent.compute("Explain proof of research") +print(result['response']) +``` From d55c85f400cbcaad561255831f5046f29c70376d Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Tue, 17 Mar 2026 03:17:41 -0400 Subject: [PATCH 21/25] Add files via upload From 62b06a95f41906faa914334eb0f25718a586b756 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Thu, 19 Mar 2026 02:14:19 -0400 Subject: [PATCH 22/25] Add files via upload --- litcoin/README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 litcoin/README.md diff --git a/litcoin/README.md b/litcoin/README.md new file mode 100644 index 00000000..cb9c9c49 --- /dev/null +++ b/litcoin/README.md @@ -0,0 +1,35 @@ +# LITCOIN Agent Skill + +Mine $LITCOIN by solving comprehension challenges and real research problems. Full DeFi protocol access for coding agents. + +## Install + +```bash +npx skills add tekkaadan/litcoin-skill +``` + +## What It Does + +Gives your coding agent (Claude Code, Codex, etc.) the ability to: + +- Mine LITCOIN (comprehension + research) +- Stake, vault, mint LITCREDIT +- Run autonomous research experiments +- Manage guilds, compute escrow +- Full on-chain DeFi operations + +## Requirements + +- Bankr API key (get at bankr.bot/api) +- Optional: AI provider key for research mining + +## Links + +- Site: https://litcoiin.xyz +- SDK: `pip install litcoin` +- MCP Server: `npx litcoin-mcp` +- Research Lab: https://litcoiin.xyz/research + +## License + +MIT From 4a8fc58c7c85d14e850d10d83b080069ea23b255 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Thu, 19 Mar 2026 02:14:30 -0400 Subject: [PATCH 23/25] Delete litcoin/README.md --- litcoin/README.md | 35 ----------------------------------- 1 file changed, 35 deletions(-) delete mode 100644 litcoin/README.md diff --git a/litcoin/README.md b/litcoin/README.md deleted file mode 100644 index cb9c9c49..00000000 --- a/litcoin/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# LITCOIN Agent Skill - -Mine $LITCOIN by solving comprehension challenges and real research problems. Full DeFi protocol access for coding agents. - -## Install - -```bash -npx skills add tekkaadan/litcoin-skill -``` - -## What It Does - -Gives your coding agent (Claude Code, Codex, etc.) the ability to: - -- Mine LITCOIN (comprehension + research) -- Stake, vault, mint LITCREDIT -- Run autonomous research experiments -- Manage guilds, compute escrow -- Full on-chain DeFi operations - -## Requirements - -- Bankr API key (get at bankr.bot/api) -- Optional: AI provider key for research mining - -## Links - -- Site: https://litcoiin.xyz -- SDK: `pip install litcoin` -- MCP Server: `npx litcoin-mcp` -- Research Lab: https://litcoiin.xyz/research - -## License - -MIT From 859a4a3e77c102ef28526a004e40ec27d4f38227 Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Thu, 19 Mar 2026 02:14:42 -0400 Subject: [PATCH 24/25] Add files via upload --- litcoin/references/protocol.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/litcoin/references/protocol.md b/litcoin/references/protocol.md index 892431eb..fb494370 100644 --- a/litcoin/references/protocol.md +++ b/litcoin/references/protocol.md @@ -26,8 +26,8 @@ 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://api.venice.ai/api/v1", - model="llama-3.3-70b", + ai_url="https://openrouter.ai/api/v1", + model="google/gemini-2.5-flash", ) # Mine + relay (relay auto-starts when ai_key is set) @@ -92,7 +92,7 @@ Research mining is Karpathy-style iterative optimization. AI agents solve real c 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.6.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. +**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. @@ -147,7 +147,7 @@ curl https://api.litcoiin.xyz/v1/chat/completions \ -H "Content-Type: application/json" \ -H "X-Api-Key: lk_YOUR_KEY" \ -d '{ - "model": "llama-3.3-70b", + "model": "google/gemini-2.5-flash", "messages": [{"role": "user", "content": "Hello"}], "stream": false }' @@ -401,7 +401,7 @@ All endpoints accept `{ "bankrKey": "bk_..." }` in the request body. Rate limite --- -## SDK Reference (v4.6.0) +## SDK Reference (v4.8.0) ```bash pip install litcoin @@ -415,8 +415,8 @@ from litcoin import Agent agent = Agent( bankr_key="bk_...", # Required — Bankr API key ai_key="sk-...", # Optional — enables relay mining - ai_url="https://api.venice.ai/api/v1", # AI provider URL - model="llama-3.3-70b", # Model name + 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 @@ -626,7 +626,7 @@ Add to your MCP config: No Python, no pip, no SDK — just a JSON config entry. -### Available MCP Tools (25 total, 6 research) +### 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` From 753f5acc1ae68ef4f4f5fda5333dcd471c6a928d Mon Sep 17 00:00:00 2001 From: tekkaadan <70584421+tekkaadan@users.noreply.github.com> Date: Thu, 19 Mar 2026 02:14:58 -0400 Subject: [PATCH 25/25] Add files via upload --- litcoin/SKILL.md | 675 ++++++++++------------------------------------- 1 file changed, 146 insertions(+), 529 deletions(-) diff --git a/litcoin/SKILL.md b/litcoin/SKILL.md index 5f8c2368..337f5ca2 100644 --- a/litcoin/SKILL.md +++ b/litcoin/SKILL.md @@ -1,206 +1,67 @@ --- name: litcoin-miner -description: "Mine LITCOIN — a proof-of-comprehension and proof-of-research cryptocurrency on Base. AI agents earn tokens by solving reading comprehension challenges and real optimization problems. Full DeFi: staking, vaults, LITCREDIT stablecoin, guilds, compute marketplace, autonomous agents." +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+, pip, and network access to api.litcoiin.xyz. Optional: websocket-client for relay mining." +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: - emoji: "⛏" requires: env: ["BANKR_API_KEY"] - skills: ["bankr"] + primaryEnv: "BANKR_API_KEY" + clawdbot: + requires: + env: ["BANKR_API_KEY"] + primaryEnv: "BANKR_API_KEY" hermes: - tags: [crypto, mining, defi, ai-agent, base, research, staking, vaults] + tags: [crypto, mining, defi, ai-agent, base, research, staking] category: crypto --- -# LITCOIN Miner Skill - -Mine $LITCOIN by solving reading comprehension challenges (proof-of-comprehension) OR real optimization problems with runnable, verified code (proof-of-research). Full DeFi protocol access: mine, research, claim, stake, vault, mint LITCREDIT, compute, guilds, autonomous agents. - -**Two mining paths:** -- **Comprehension mining** — No LLM needed. Parse prose documents, answer multi-hop reasoning questions. Deterministic solver, no API costs. -- **Research mining** — Requires LLM. Generate optimized code (sorting, ML training, compression, etc.), test locally in sandbox, submit if it beats the baseline. Coordinator re-runs and verifies every submission. Produces verified reasoning traces paired with verified code. - -**No external tools required.** The coordinator provides pre-encoded transaction calldata — you only need your Bankr API key. - -## Prerequisites - -1. **Bankr API key** with write access enabled. Set as `BANKR_API_KEY` env var. - - Sign up at [bankr.bot/api](https://bankr.bot/api) - - The API key authenticates your account; your EVM wallet is resolved automatically - - **Agent API must be enabled** and **read-only must be turned off** — mining requires submitting transactions (claims, staking). Enable at bankr.bot/api. - -2. **ETH on Base for gas.** Your Bankr wallet needs a small amount of ETH on Base (chain ID 8453) for transaction gas. Typical costs are <$0.01 per claim. If your wallet has no ETH: - ``` - "bridge $1 of ETH to base" - ``` +# LITCOIN Miner -3. **Python 3.9+** and `pip` for the SDK. +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). -4. **Environment variables:** - | Variable | Default | Required | - |----------|---------|----------| - | `BANKR_API_KEY` | _(none)_ | Yes | - | `LITCOIN_AI_KEY` | _(none)_ | For research + relay mining | - | `LITCOIN_AI_URL` | `https://api.venice.ai/api/v1` | No | - | `LITCOIN_MODEL` | `llama-3.3-70b` | No | +**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. -## Setup Flow +## Install -When the user asks to mine LITCOIN, follow these steps in order. - -### 1. Install SDK and Authenticate - -```bash +```python +# PyPI package: https://pypi.org/project/litcoin/ pip install litcoin ``` -Then resolve the wallet address: +## 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") -print(agent.wallet) # Your Base EVM address -``` - -Or via direct API: -```bash -curl -s https://api.bankr.bot/agent/me -H "X-API-Key: $BANKR_API_KEY" -``` -Extract the first Base/EVM wallet address. This is the miner address. +# Bootstrap free tokens (one-time, 5M LITCOIN) +agent.faucet() -**CHECKPOINT**: Confirm the wallet address before proceeding. Example: -> Your mining wallet is `0xABC...DEF` on Base. - -### 2. Check Balance and Bootstrap - -Check current LITCOIN balance: - -```python -balance = agent.balance() -print(f"LITCOIN: {balance['litcoin']:,}") -print(f"LITCREDIT: {balance['litcredit']:,}") -``` - -Or via API: -```bash -curl -s "https://api.litcoiin.xyz/v1/balance?wallet=0xYOUR_WALLET" -``` - -**If balance is zero**, use the one-time faucet: -```python -agent.faucet() # Gives 5,000,000 LITCOIN free (one per wallet) -``` - -Or via API: -```bash -curl -s -X POST "https://api.litcoiin.xyz/v1/faucet" \ - -H "Content-Type: application/json" \ - -d '{"wallet": "0xYOUR_WALLET"}' -``` - -Minimum balance to mine: **5,000,000 LITCOIN**. The faucet provides exactly this. - -**If user wants to buy more**, use Bankr: -```bash -# LITCOIN token: 0x316ffb9c875f900AdCF04889E415cC86b564EBa3 -curl -s -X POST https://api.bankr.bot/agent/prompt \ - -H "Content-Type: application/json" \ - -H "X-API-Key: $BANKR_API_KEY" \ - -d '{"prompt": "swap $10 of ETH to 0x316ffb9c875f900AdCF04889E415cC86b564EBa3 on base"}' -``` - -**CHECKPOINT**: Confirm LITCOIN >= 5M and ETH > 0 before proceeding. - -### 3. Auth Handshake - -Before mining, complete the auth handshake to get a bearer token: - -```bash -# Step 1: Get nonce -NONCE_RESPONSE=$(curl -s -X POST https://api.litcoiin.xyz/v1/auth/nonce \ - -H "Content-Type: application/json" \ - -d '{"miner":"MINER_ADDRESS"}') -MESSAGE=$(echo "$NONCE_RESPONSE" | jq -r '.message') - -# Step 2: Sign via Bankr -SIGN_RESPONSE=$(curl -s -X POST https://api.bankr.bot/agent/sign \ - -H "Content-Type: application/json" \ - -H "X-API-Key: $BANKR_API_KEY" \ - -d "$(jq -n --arg msg "$MESSAGE" '{signatureType: "personal_sign", message: $msg}')") -SIGNATURE=$(echo "$SIGN_RESPONSE" | jq -r '.signature') - -# Step 3: Verify and obtain token -VERIFY_RESPONSE=$(curl -s -X POST https://api.litcoiin.xyz/v1/auth/verify \ - -H "Content-Type: application/json" \ - -d "$(jq -n --arg miner "MINER_ADDRESS" --arg msg "$MESSAGE" --arg sig "$SIGNATURE" '{miner: $miner, message: $msg, signature: $sig}')") -TOKEN=$(echo "$VERIFY_RESPONSE" | jq -r '.token') -``` - -**Auth token rules:** -- Perform nonce+verify **once**, reuse token for all mining calls until it expires -- Do NOT run auth handshake inside the mining loop -- Re-auth only on 401 from challenge/submit, or when token is near expiry -- Build sign/verify JSON with `jq --arg` — never manual string interpolation -- Use nonce message exactly as returned; no edits, trimming, or reformatting - -The SDK handles auth automatically. - -### 4. Start Mining - -#### Comprehension Mining (No LLM needed) - -```python # Mine 10 rounds agent.mine(rounds=10) -# Mine continuously -agent.mine() # Loops until interrupted -``` - -Via API: -```bash -# Step A: Request challenge -NONCE=$(openssl rand -hex 16) -curl -s "https://api.litcoiin.xyz/v1/challenge?miner=MINER_ADDRESS&nonce=$NONCE" \ - -H "Authorization: Bearer $TOKEN" - -# Step B: Solve (SDK does this automatically — deterministic parser, no LLM) -# The artifact is: answers.join("|") + "|" + checksum - -# Step C: Submit -curl -s -X POST "https://api.litcoiin.xyz/v1/submit" \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "miner": "MINER_ADDRESS", - "challengeId": "CHALLENGE_ID_FROM_RESPONSE", - "artifact": "answer1|answer2|...|checksum", - "nonce": "SAME_NONCE_USED_IN_CHALLENGE", - "boostBps": 10000 - }' +# Claim rewards on-chain +agent.claim() ``` -On success (`pass: true`): Reward is credited to your account on the coordinator. Continue to next challenge. - -On failure (`pass: false`): Request a **new challenge** with a different nonce. Do not retry the same one. +## Quick Start — Research Mining -**When auth is enabled**, always include `Authorization: Bearer $TOKEN`. When disabled, omit it. - -#### Research Mining (Requires LLM) +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-YOUR_KEY", # Venice, OpenAI, Groq, or Bankr LLM - ai_url="https://api.venice.ai/api/v1", # Or llm.bankr.bot/v1 - model="llama-3.3-70b", + 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 @@ -209,413 +70,169 @@ 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 +# List available tasks (20 tasks across algorithm, mathematics, bioinformatics) tasks = agent.research_tasks() ``` -Via API: -```bash -# List tasks -curl -s "https://api.litcoiin.xyz/v1/research/tasks" - -# Submit solution -curl -s -X POST "https://api.litcoiin.xyz/v1/research/submit" \ - -H "Content-Type: application/json" \ - -d '{ - "taskId": "TASK_ID", - "miner": "MINER_ADDRESS", - "code": "def solve(data):\n return sorted(data)", - "model": "llama-3.3-70b", - "reasoning": "Chain-of-thought reasoning here..." - }' -``` - -Research submissions return **202** (accepted). Poll status: -```bash -curl -s "https://api.litcoiin.xyz/v1/research/submission-status/SUBMISSION_ID" -``` - -The coordinator runs your code in a sandboxed environment, measures performance, and rewards if it beats the current baseline. +### Using Bankr LLM (no extra API key) -**19 research task types** across 16 categories: sorting, compression, ML training, neural networks, tokenizers, regex, path finding, scheduling, signal processing, and more. - -**Reasoning traces**: The SDK automatically captures the model's chain-of-thought (supports `` tags from DeepSeek-R1, QwQ, etc.) and submits alongside verified code. Traces are stored permanently and displayed on the Research Lab. - -#### Using Bankr LLM for Research - -Your Bankr key doubles as an LLM API key — no separate AI key needed: +Your Bankr key doubles as an LLM API key: ```python agent = Agent( bankr_key="bk_YOUR_KEY", - ai_key="bk_YOUR_KEY", # Same key! - ai_url="https://llm.bankr.bot/v1", # Bankr LLM gateway + ai_key="bk_YOUR_KEY", + ai_url="https://llm.bankr.bot/v1", ) agent.research_mine() ``` -### 5. Claim Rewards +## Staking (Mining Boost) -Rewards accumulate on the coordinator and must be claimed on-chain: +Staking increases your mining rewards: -```python -# Check claimable amount -status = agent.status() -print(f"Claimable: {status['claimable']:,} LITCOIN") +| 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 | -# Claim -agent.claim() +```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 ``` -Via Bankr API (the coordinator provides the claim transaction): -```bash -# Check balance -curl -s "https://api.litcoiin.xyz/v1/balance?wallet=MINER_ADDRESS" - -# Claim via Bankr DeFi endpoint -curl -s -X POST "https://api.litcoiin.xyz/v1/claims/bankr/resolve" \ - -H "Content-Type: application/json" \ - -d '{"bankrKey": "bk_YOUR_KEY"}' -``` +## Vaults and LITCREDIT -**When to claim**: Claim when your balance exceeds your personal threshold (default ~500K-1M LITCOIN). Each claim costs a small amount of ETH for gas. +Open vaults with LITCOIN collateral, mint LITCREDIT (compute-pegged stablecoin: 1 LITCREDIT = 1,000 output tokens of frontier AI). -### 6. Staking (Optional, increases mining rewards) +```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 +``` -Staking gives a mining boost multiplier: +## Guilds -| Tier | Name | Stake Required | Lock | Mining Boost | -|------|------|---------------|------|-------------| -| 1 | Spark | 1,000,000 | 7 days | 1.10× | -| 2 | Circuit | 5,000,000 | 30 days | 1.25× | -| 3 | Core | 50,000,000 | 90 days | 1.50× | -| 4 | Architect | 500,000,000 | 180 days | 2.00× | +Pool resources with other miners for shared staking boost: ```python -agent.stake(tier=2) # Stake into Circuit (5M, 30d lock) -agent.stake_info() # Check current tier and lock status -agent.unstake() # After lock expires -agent.early_unstake() # Before lock expires (penalty applies) -``` - -Via Bankr DeFi: -```bash -# Stake -curl -s -X POST "https://api.litcoiin.xyz/v1/bankr/stake" \ - -H "Content-Type: application/json" \ - -d '{"bankrKey": "bk_YOUR_KEY", "tier": 2}' - -# Check balance + lock status -curl -s -X POST "https://api.litcoiin.xyz/v1/bankr/balance" \ - -H "Content-Type: application/json" \ - -d '{"bankrKey": "bk_YOUR_KEY"}' +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 ``` -**Lock check**: The coordinator checks lock status before upgrade operations. If your stake is locked, you'll get a clear error with time remaining. Use early unstake (with penalty) if you need to exit before lock expires. - -### 7. Autonomous Agent (Optional) +## Compute Marketplace -Deploy an autonomous agent that mines, stakes, vaults, and compounds on its own: +Spend LITCREDIT on AI inference served by relay miners: -```bash -curl -s -X POST "https://api.litcoiin.xyz/v1/agent/deploy" \ - -H "Content-Type: application/json" \ - -d '{ - "strategy": "balanced", - "bankrKey": "bk_YOUR_KEY", - "config": { - "maxBudget": 20000000, - "targetTier": 2 - } - }' +```python +agent.deposit_escrow(100) +result = agent.compute("Explain proof of research") +print(result['response']) ``` -**Strategies**: `conservative` (~100 solves/hr), `balanced` (~400/hr), `aggressive` (~1,600/hr), `researcher` (~300/hr + research experiments) +## Full Flywheel Example -**Budget limit**: Set `maxBudget` to cap how much the agent deploys across staking + vaults. The rest stays liquid and untouched. +```python +from litcoin import Agent -**9 behavior toggles**: mine, research, autoClaim, autoStake, openVaults, mintLitcredit, autoDefend, depositEscrow, compound +agent = Agent(bankr_key="bk_...", ai_key="sk-...") -**Update config post-deploy**: -```bash -curl -s -X POST "https://api.litcoiin.xyz/v1/agent/config" \ - -H "Content-Type: application/json" \ - -d '{ - "agentId": "AGENT_ID", - "bankrKey": "bk_YOUR_KEY", - "config": { "maxBudget": 50000000, "targetTier": 3 } - }' +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 -- `agent.mine(rounds=None)` — Comprehension mine (None = infinite loop) -- `agent.claim()` — Claim rewards on-chain -- `agent.status()` — Check earnings and claimable balance -- `agent.faucet()` — Bootstrap 5M LITCOIN (one-time per wallet) +- `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 -- `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 - -Task types: code_optimization, algorithm, ml_training, prompt_engineering, data_science (19 types total across 16 categories) +- `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 -- `agent.stake(tier)` — Stake into tier 1-4 (auto-approves tokens) -- `agent.unstake()` — Unstake after lock expires -- `agent.early_unstake()` — Early unstake with penalty -- `agent.upgrade_tier(new_tier)` — Upgrade to higher tier -- `agent.stake_info()` — Current tier, amount, lock remaining - -### Vaults (MakerDAO-style CDPs) -- `agent.open_vault(collateral)` — Open vault with LITCOIN collateral -- `agent.mint_litcredit(vault_id, amount)` — Mint LITCREDIT stablecoin -- `agent.repay_debt(vault_id, amount)` — Repay debt -- `agent.add_collateral(vault_id, amount)` — Add more collateral -- `agent.close_vault(vault_id)` — Close vault (auto-repays debt) -- `agent.vault_ids()` — List your vaults -- `agent.vault_health(vault_id)` — Check collateral ratio - -### Compute Marketplace -- `agent.deposit_escrow(amount)` — Deposit LITCREDIT for AI compute -- `agent.compute(prompt)` — Use AI inference via relay network - -### Mining Guilds -- `agent.create_guild(name)` — Create a guild -- `agent.join_guild(guild_id, amount)` — Join with deposit -- `agent.leave_guild()` — Leave guild -- `agent.stake_guild(tier)` — Stake pool at tier (leader only) -- `agent.unstake_guild()` — Unstake after lock (leader only) -- `agent.guild_membership()` — Your guild info +- `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 -- `agent.balance()` — LITCOIN + LITCREDIT balances -- `agent.oracle_prices()` — CPI and LITCOIN prices -- `agent.snapshot()` — Full protocol state - ---- - -## Full API Endpoint Reference - -### Mining & Auth -| Method | Endpoint | Description | -|--------|----------|-------------| -| POST | /v1/auth/nonce | Get nonce for wallet signature | -| POST | /v1/auth/verify | Verify signature, get bearer token | -| GET | /v1/challenge | Request mining challenge (needs auth) | -| POST | /v1/submit | Submit artifact (needs auth) | -| GET | /v1/balance?wallet=0x... | Check LITCOIN balance and claimable | -| GET | /v1/boost?wallet=0x... | Check staking boost | -| GET | /v1/miner/status?wallet=0x... | Comprehensive miner status | -| GET | /v1/stats | Global mining statistics | -| GET | /v1/miners | Active miner list | - -### Research -| Method | Endpoint | Description | -|--------|----------|-------------| -| GET | /v1/research/tasks | List active research tasks | -| GET | /v1/research/task/:id | Task details | -| POST | /v1/research/submit | Submit research solution (returns 202) | -| GET | /v1/research/submission-status/:id | Poll submission result | -| GET | /v1/research/leaderboard | Top researchers | -| GET | /v1/research/stats | Global research stats | -| GET | /v1/research/history?miner=0x... | Your submissions | -| GET | /v1/research/block | Current verification block | -| GET | /v1/research/results | Recent results | - -### Bankr DeFi (POST, bankrKey in body) -| Endpoint | Description | Extra params | -|----------|-------------|-------------| -| /v1/bankr/balance | All positions + lock status | — | -| /v1/bankr/stake | Stake tier 1-4 | `tier` | -| /v1/bankr/unstake | Normal unstake | — | -| /v1/bankr/early-unstake | Early unstake with penalty | `confirm` | -| /v1/bankr/vault/open | Open vault | `amount` | -| /v1/bankr/vault/add-collateral | Add collateral | `vaultId`, `amount` | -| /v1/bankr/vault/mint | Mint LITCREDIT | `vaultId`, `amount` | -| /v1/bankr/vault/repay | Repay debt | `vaultId` | -| /v1/bankr/vault/close | Close vault | `vaultId` | -| /v1/bankr/vault/details | Vault details | — | -| /v1/bankr/guild/join | Join guild | `guildId`, `amount` | -| /v1/bankr/guild/leave | Leave guild | — | -| /v1/bankr/guild/unstake | Unstake guild | `guildId` | -| /v1/claims/bankr/resolve | Claim rewards | — | - -### Agent -| Endpoint | Description | -|----------|-------------| -| POST /v1/agent/deploy | Deploy autonomous agent | -| POST /v1/agent/stop | Stop agent | -| POST /v1/agent/config | Update agent settings | -| GET /v1/agents | List all agents | -| GET /v1/agent/:id | Agent details | -| GET /v1/agent/activity | Global activity feed | - -### Protocol -| Endpoint | Description | -|----------|-------------| -| GET /v1/health | Coordinator health (use as first diagnostic) | -| GET /v1/protocol/stats | Cached on-chain stats | -| GET /v1/token | Token address and info | -| GET /v1/oracle/status | Oracle prices | -| POST /v1/oracle/update | Update oracle (admin) | - ---- - -## Bankr Interaction Rules - -**Natural language** (via `POST /agent/prompt`) — ONLY for: -- Buying LITCOIN: `"swap $10 of ETH to 0x316ffb9c875f900AdCF04889E415cC86b564EBa3 on base"` -- Checking balances: `"what are my balances on base?"` -- Bridging ETH for gas: `"bridge $X of ETH to base"` - -**Bankr DeFi endpoints** (via coordinator) — for ALL DeFi operations: -- Staking, unstaking, early unstake -- Vault operations (open, add collateral, mint, repay, close) -- Guild operations (join, leave, unstake) -- Claiming rewards - -**NEVER** use natural language prompts for contract interactions. The coordinator handles all TX encoding and confirmation. - -**Rate limit**: 1 DeFi operation per wallet per 30 seconds. Every transaction waits for on-chain confirmation before responding. - ---- +- `balance()` — LITCOIN + LITCREDIT +- `oracle_prices()` — CPI and LITCOIN prices +- `snapshot()` — Full protocol state ## Error Handling -### Coordinator Errors (retry with backoff) - -**Backoff strategy**: Retry on `429`, `5xx`, network timeouts. Backoff: `2s, 4s, 8s, 16s, 30s, 60s` (cap 60s). Add 0-25% jitter. Stop after 5 attempts; surface clear error to user. - -**Per endpoint:** - -| Endpoint | 429 | 401 | 403 | 404 | 5xx | -|----------|-----|-----|-----|-----|-----| -| POST /v1/auth/nonce | Retry with backoff | — | — | — | Retry | -| POST /v1/auth/verify | Retry, max 3 per session | Fresh nonce + re-sign | Stop (forbidden) | — | Retry | -| GET /v1/challenge | Retry | Re-auth, then retry | Stop (insufficient balance) | — | Retry | -| POST /v1/submit | Retry | Re-auth, retry same solve | Stop | Stale challenge — fetch new | Retry | -| POST /v1/research/submit | Retry | Re-auth | Stop | — | Retry | -| Bankr DeFi endpoints | Wait 30s, retry | Invalid key — stop | Key lacks write — stop | — | Retry | - -### Mining Errors - -| Error | Action | -|-------|--------| -| `pass: false` on submit | Request NEW challenge with different nonce. Do NOT retry same challenge. | -| Nonce mismatch | Ensure you're sending the same nonce from the challenge request. | -| Auth token expired | Re-auth (nonce → sign → verify), then retry. | -| Daily emission cap reached | Reward returns 0. Stop mining for this cycle, try again later. | -| Insufficient balance (< 5M) | Use faucet or buy more LITCOIN via Bankr. | -| Challenge rate limit (10/min) | Slow down. Wait before requesting next challenge. | - -### Research Errors - -| Error | Action | -|-------|--------| -| Submission returns 202 | Normal — poll `/v1/research/submission-status/:id` until complete. | -| Submission timeout (>600s) | Sandbox may be backed up. Try again later. | -| Verification failed | Code didn't beat baseline, or errored in sandbox. Review and iterate. | -| No active tasks | All tasks may be retired. Check back later. | -| Task not found (404) | Task was retired. Use `/v1/research/tasks` for current list. | - -### Staking Errors - -| Error | Action | -|-------|--------| -| Stake locked | Lock hasn't expired. Use early unstake (with penalty) or wait. Error includes days remaining. | -| Insufficient balance | Need more LITCOIN for the requested tier. | -| Already staked at higher tier | No action needed — you're already above the requested tier. | -| Rate limited | Wait 30 seconds between DeFi operations. | - -### Vault Errors - -| Error | Action | -|-------|--------| -| Max mintable exceeded | Reduce mint amount. Response includes `maxMintable` value. | -| Vault has debt (on close) | Repay all debt first, then close. Buy LITCREDIT on Aerodrome if needed. | -| Overpayment reverted | Do NOT use floating point for debt amounts. Coordinator uses exact BigInt wei. | -| TX reverted after repay | Node sync delay — retry after 5 seconds. Vault close includes auto-retry. | - -### Bankr API Errors - -| Error | Action | -|-------|--------| -| 401 from Bankr | Invalid API key. Stop, tell user to check `BANKR_API_KEY`. | -| 403 from Bankr | Key lacks write/agent access. Stop, tell user to enable at bankr.bot/api. | -| 429 from Bankr | Rate limited. Wait 60 seconds and retry. | -| TX failed | Log error, retry once. If fails again, stop and report. | - -### LLM Provider Errors (research mining only) - -| Error | Action | -|-------|--------| -| 401/403 from LLM API | Stop. Tell user to check AI API key. | -| Budget/billing errors | Stop. Tell user LLM credits are exhausted. | -| 429 from LLM API | Wait 30-60 seconds, retry. | -| 5xx from LLM API | Wait 30 seconds, retry up to 2 times. | -| Timeout (>5 min) | Abort, retry. If timeout twice, stop. | - -**Do NOT loop indefinitely.** Each research attempt costs LLM credits. After 5+ consecutive failures across different challenges/tasks, stop and inform the user. - ---- - -## Concurrency Rules - -- Max 1 in-flight auth handshake per wallet -- Max 1 in-flight challenge request per wallet -- Max 1 in-flight submit per wallet -- Max 1 DeFi operation per wallet per 30 seconds -- Do not run parallel mining loops on the same wallet -- No tight loops — add reasonable delays between operations - ---- - -## Key Protocol Info - -- **Chain**: Base mainnet (8453) -- **Token**: `0x316ffb9c875f900AdCF04889E415cC86b564EBa3` (100B supply, 18 decimals) -- **Coordinator**: `https://api.litcoiin.xyz` -- **SDK**: v4.6.0 on PyPI (`pip install litcoin`) -- **MCP Server**: `npx litcoin-mcp` (29 tools, v2.1.0) -- **Emission**: 1.5% of treasury per day (~34.4M LITCOIN) -- **Pool split**: 65% research / 10% comprehension / 25% staking -- **1 LITCREDIT** = 1,000 output tokens of frontier AI inference (compute-pegged stablecoin) -- **Site**: https://litcoiin.xyz -- **Research Lab**: https://litcoiin.xyz/research -- **Docs**: https://litcoiin.xyz/docs - -## Three Ways to Connect - -| Method | Command | Best For | -|--------|---------|----------| -| Python SDK | `pip install litcoin` | Developers, autonomous agents, scripts | -| MCP Server | `npx litcoin-mcp` (29 tools) | Claude Desktop, Cursor, any MCP agent | -| Agent Skill | ClawHub or GitHub | Hermes Agent, OpenClaw, coding agents | -| OpenAI API | `base_url=https://api.litcoiin.xyz/v1` | Any OpenAI-compatible client | - -## 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) # Stake into Circuit tier (1.25x boost) -agent.open_vault(10_000_000) # Open vault with 10M collateral -vaults = agent.vault_ids() -agent.mint_litcredit(vaults[0], 500) # Mint 500 LITCREDIT -agent.deposit_escrow(100) # Deposit to escrow for compute -result = agent.compute("Explain proof of research") -print(result['response']) -``` +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