litcoin 4.7.0

LITCOIN SDK — Proof-of-comprehension and proof-of-research mining, staking, vaults, LITCREDIT, guilds, autonomous agents, and compute for AI agents on Base

litcoin

Python SDK for the LITCOIN proof-of-comprehension and proof-of-research protocol on Base.

Mine, research, stake, vault, mint LITCREDIT, manage guilds, deploy autonomous agents — all from Python.

Install

pip install litcoin

Quick Start

from litcoin import Agent

agent = Agent(
    bankr_key="bk_YOUR_KEY",        # Required — get at bankr.bot/api
    ai_key="sk-YOUR_KEY",           # Optional — for research + relay mining
    ai_url="https://api.venice.ai/api/v1",
    model="llama-3.3-70b",
)

# Mine (comprehension — no LLM needed)
agent.mine(rounds=10)

# Research mine (requires ai_key)
agent.research_mine()

# Claim rewards on-chain
agent.claim()

# Stake for mining boost
agent.stake(tier=2)  # Circuit tier: 5M LITCOIN, 30d lock, 1.25x boost

Bankr LLM (no extra API key)

Your Bankr key doubles as an LLM API key:

agent = Agent(
    bankr_key="bk_YOUR_KEY",
    ai_key="bk_YOUR_KEY",              # Same key
    ai_url="https://llm.bankr.bot/v1", # Bankr LLM gateway
)
agent.research_mine()

Full Flywheel

agent.mine(rounds=20)                   # Comprehension mine
agent.research_loop(rounds=10)          # Research mine
agent.claim()                           # Claim on-chain
agent.stake(2)                          # Stake Circuit (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 escrow
result = agent.compute("Explain proof of research")
print(result['response'])

API Reference

Mining

Method	Description
mine(rounds=None)	Comprehension mine (None = infinite)
claim()	Claim rewards on-chain
status()	Check earnings and claimable
faucet()	Bootstrap 5M free LITCOIN (one-time)
balance()	LITCOIN + LITCREDIT balances

Research Mining

Method	Description
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

Method	Description
stake(tier)	Stake tier 1-4 (auto-approve)
unstake()	Unstake after lock expires
early_unstake(confirm=False)	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
tier()	Current tier number

Vaults

Method	Description
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

Method	Description
deposit_escrow(amount)	Deposit LITCREDIT
compute(prompt)	AI inference via relay

Guilds

Method	Description
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

Method	Description
balance()	LITCOIN + LITCREDIT
oracle_prices()	CPI + LITCOIN prices
snapshot()	Full protocol state

Staking Tiers

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

Error Handling

The SDK raises exceptions with clear messages. Common errors:

Error	Cause	Fix
Insufficient balance	Not enough LITCOIN	Use faucet() or buy more
Stake locked for X days	Unstake attempted during lock	Use early_unstake() or wait
Not staked	Unstake when not staked	Stake first
Daily cap reached	Mining reward returns 0	Wait for next day
Max mintable exceeded	Minting more LITCREDIT than allowed	Reduce amount
Vault has debt	Close vault with outstanding debt	repay_debt() first
Rate limited	Too many operations	Wait 30s between DeFi ops
Invalid API key	Bad Bankr key	Check key at bankr.bot/api

Key Info

• Chain: Base mainnet (8453)
• Token: 0x316ffb9c875f900AdCF04889E415cC86b564EBa3
• SDK version: 4.7.0
• Python: 3.9+
• Emission: 1.5%/day (~34.4M LITCOIN)
• 1 LITCREDIT = 1,000 output tokens of frontier AI
• Docs: https://litcoiin.xyz/docs
• Site: https://litcoiin.xyz

Also Available

Method	Command	Best For
MCP Server	npx litcoin-mcp (43 tools)	Claude Desktop, Cursor
Agent Skill	ClawHub / GitHub	Hermes, OpenClaw
OpenAI API	base_url=https://api.litcoiin.xyz/v1	Any OpenAI client

Changelog

4.7.0 (March 2026)

• Added early_unstake(confirm) — preview/execute early unstake with penalty
• Added faucet() — one-time 5M LITCOIN bootstrap
• Updated description and README with full API reference, error handling, staking tiers

4.6.0

• Reasoning trace capture for research mining
• Research history and leaderboard methods

4.5.1

• Guild unstake, guild yield methods
• Relay mining improvements