Litcoin Miner

Other

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.

Install

openclaw skills install litcoin-miner

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

Bankr API key with write access enabled. Set as BANKR_API_KEY env var.
- Sign up at 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.
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"
```
Python 3.9+ and pip for the SDK.
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

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

pip install litcoin

Then resolve the wallet address:

from litcoin import Agent

agent = Agent(bankr_key="bk_YOUR_KEY")
print(agent.wallet)  # Your Base EVM address

Or via direct API:

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:

balance = agent.balance()
print(f"LITCOIN: {balance['litcoin']:,}")
print(f"LITCREDIT: {balance['litcredit']:,}")

Or via API:

curl -s "https://api.litcoiin.xyz/v1/balance?wallet=0xYOUR_WALLET"

If balance is zero, use the one-time faucet:

agent.faucet()  # Gives 5,000,000 LITCOIN free (one per wallet)

Or via API:

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:

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

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

# Mine 10 rounds
agent.mine(rounds=10)

# Mine continuously
agent.mine()  # Loops until interrupted

Via API:

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

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",
)

# Single research cycle
result = agent.research_mine()

# Iterate on one task (this is where breakthroughs happen)
agent.research_loop(task_id="sort-benchmark-001", rounds=50, delay=30)

# List available tasks
tasks = agent.research_tasks()

Via API:

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

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.

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

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

5. Claim Rewards

Rewards accumulate on the coordinator and must be claimed on-chain:

# Check claimable amount
status = agent.status()
print(f"Claimable: {status['claimable']:,} LITCOIN")

# Claim
agent.claim()

Via Bankr API (the coordinator provides the claim transaction):

# 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"}'

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)

Staking gives a mining boost multiplier:

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×

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:

# 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"}'

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:

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
    }
  }'

Strategies: conservative (~100 solves/hr), balanced (~400/hr), aggressive (~1,600/hr), researcher (~300/hr + research experiments)

Budget limit: Set maxBudget to cap how much the agent deploys across staking + vaults. The rest stays liquid and untouched.

9 behavior toggles: mine, research, autoClaim, autoStake, openVaults, mintLitcredit, autoDefend, depositEscrow, compound

Update config post-deploy:

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 }
  }'

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)

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)

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

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.

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

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'])