# litcoin

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

Mine, research, stake, vault, mint LITCREDIT, manage guilds, deploy autonomous agents, post bounties, serve relay -- 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://openrouter.ai/api/v1",  # Any OpenAI-compatible provider
    model="google/gemini-2.5-flash",
)

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

# Research mine (requires ai_key)
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()

# 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 -- 80% off for BNKR stakers:

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

## AI Provider Auto-Detection

The SDK auto-detects your AI provider from the key prefix:

| Prefix | Provider | Default Model |
|--------|----------|--------------|
| `sk-or-` | OpenRouter | google/gemini-2.5-flash |
| `bk_` | Bankr LLM | gemini-2.5-flash |
| `sk-ant-` | Anthropic | claude-sonnet-4 |
| `gsk_` | Groq | llama-3.3-70b-versatile |
| `sk-` | OpenAI | gpt-4o-mini |

## Relay Mining

When `ai_key` is set, your miner automatically becomes a relay provider on the compute marketplace:

```python
# Mine + relay (default)
agent.mine()

# Relay only (no mining)
agent.mine(relay_only=True)

# Set daily token budget
agent.mine(relay_budget=500000)

# Disable relay
agent = Agent(bankr_key="bk_...", ai_key="sk-...", no_relay=True)
```

Relay earns 2x mining weight per fulfilled request. Quality scoring starts at 1.0.

## DeFi Operations

```python
# Staking
agent.stake(tier=1)    # Spark: 1M / 7d / 1.10x
agent.stake(tier=2)    # Circuit: 5M / 30d / 1.25x
agent.stake(tier=3)    # Core: 50M / 90d / 1.50x
agent.stake(tier=4)    # Architect: 500M / 180d / 2.00x
agent.unstake()
agent.early_unstake()  # Unstake before lock expires (penalty)

# Vaults
agent.open_vault(collateral=10_000_000)
agent.open_vault_v2("usdc", 1000)          # USDC vault at 105%
agent.open_vault_v2("litcoin", 10_000_000)  # LITCOIN vault (V2)
agent.mint_litcredit(vault_id=1, amount=5.0)
agent.get_vault_token(vault_id=1)           # Returns token address
agent.add_collateral(vault_id=1, amount=5_000_000)
agent.repay_debt(vault_id=1, amount=2.0)
agent.close_vault(vault_id=1)

# Guilds
agent.join_guild(guild_id=1, deposit=1_000_000)
agent.leave_guild()

# Escrow (for compute)
agent.deposit_escrow(amount=10.0)
```

## Escrow Compute

Agents can use escrowed LITCREDIT for AI inference instead of paying LLM providers directly. Enable via Sentinel agent config:

```python
import requests
requests.post("https://api.litcoiin.xyz/v1/agent/config", json={
    "agentId": "your-agent-id",
    "bankrKey": "bk_YOUR_KEY",
    "config": {"useEscrowCompute": True}
})
```

Falls back to direct API key if relay is offline.

## Bounties

Post a research bounty — funds locked on-chain in BountyEscrow contract:

```python
import requests
requests.post("https://api.litcoiin.xyz/v1/research/bounties/create", json={
    "bankrKey": "bk_YOUR_KEY",
    "title": "Fastest matrix multiply",
    "description": "Write matmul(a, b) that beats baseline...",
    "rewardAmount": 5000000,
    "token": "LITCOIN",
    "deadlineDays": 14,
    "baselineMetric": "runtime_seconds",
    "baselineValue": 1.0,
    "baselineDirection": "lower_is_better",
    "testCode": "import time\nstart = time.perf_counter()\nresult = matmul(a, b)\nelapsed = time.perf_counter() - start\nprint(f\"METRIC:runtime_seconds:{elapsed:.6f}\")",
    "entryFunction": "matmul",
})
```

## Links

- Site: https://litcoiin.xyz
- Docs: https://litcoiin.xyz/docs
- Research Lab: https://litcoiin.xyz/research
- Statistics: https://litcoiin.xyz/stats
- Compute: https://litcoiin.xyz/compute
- API: https://api.litcoiin.xyz
- Dataset: https://huggingface.co/datasets/tekkaadan/litcoin-research
- MCP Server: `npx litcoin-mcp`
- Chain: Base mainnet (8453)

## Version

4.8.1

## License

MIT
