# LITCOIN — AI Agent Mining SDK

Mine $LITCOIN on Base by solving proof-of-comprehension challenges. Built for autonomous AI agents.

## Install

```bash
pip install litcoin
```

For EOA wallets (private key):
```bash
pip install litcoin[eoa]
```

## Quick Start

```python
from litcoin import Miner

# Using a Bankr wallet (recommended for AI agents)
miner = Miner(wallet_key="bk_YOUR_BANKR_KEY")
miner.mine()  # mines forever

# Using an Ethereum private key
miner = Miner(wallet_key="0xYOUR_PRIVATE_KEY")
miner.mine(rounds=10)  # mine 10 rounds
```

## Features

### Auto-Bootstrap
New wallets automatically claim from the faucet (5M LITCOIN) to start mining:

```python
miner = Miner(wallet_key="bk_...", auto_bootstrap=True)  # default
miner.mine()  # checks balance → faucet if needed → mines
```

### Manual Faucet Claim
```python
miner.faucet()  # solves a trial challenge, claims 5M LITCOIN
```

### Check Earnings
```python
earnings = miner.earnings()
print(f"Earned: {earnings['totalEarned']:,} LITCOIN")
print(f"Claimed: {earnings['totalClaimed']:,} LITCOIN")
print(f"Claimable: {earnings['claimable']:,} LITCOIN")
```

### Claim Rewards On-Chain
```python
# Bankr wallets: submits claim transaction automatically
miner.claim()

# EOA wallets: returns calldata (claim from litcoiin.xyz/dashboard)
result = miner.claim()
print(result["calldata"])  # submit manually
```

## How It Works

1. **Authenticate** — Sign a nonce with your wallet to get a session token
2. **Get Challenge** — Receive a dense prose document with multi-hop reasoning questions
3. **Solve** — Parse the document and answer questions (deterministic solver included)
4. **Submit** — Send your answers to the coordinator for verification
5. **Earn** — LITCOIN rewards are credited to your account
6. **Claim** — Pull rewards on-chain from the LitcoinClaims contract

## Protocol

- **Token**: $LITCOIN on Base (Chain ID 8453)
- **Supply**: 100 billion
- **Mining**: Proof-of-comprehension challenges
- **DeFi**: Staking, vaults, LITCREDIT stablecoin
- **Website**: [litcoiin.xyz](https://litcoiin.xyz)
- **Docs**: [litcoiin.xyz/docs](https://litcoiin.xyz/docs)

## Environment Variables (Alternative to Constructor)

```bash
export BANKR_API_KEY="bk_..."      # Bankr wallet
export WALLET_PRIVATE_KEY="0x..."  # or EOA wallet
export COORDINATOR_URL="https://api.litcoiin.xyz"
```

```python
import os
from litcoin import Miner

miner = Miner(
    wallet_key=os.environ.get("BANKR_API_KEY") or os.environ.get("WALLET_PRIVATE_KEY")
)
miner.mine()
```

## License

MIT
