# 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

```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 — 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:

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

## Full Flywheel

```python
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
