Metadata-Version: 2.4
Name: litcoin
Version: 4.15.2
Summary: LITCOIN SDK. Proof-of-comprehension and proof-of-research mining, staking, vaults, LITCREDIT, guilds, autonomous agents, compute, and TCG intelligence (Pokemon, Magic, Yu-Gi-Oh, One Piece, Greed Island) for AI agents on Base.
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.32.0
Requires-Dist: websocket-client>=1.6.0

# 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, and query TCG intelligence (Pokemon, Magic, Yu-Gi-Oh, One Piece, Greed Island) -- 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.litcoin.app/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.litcoin.app/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://litcoin.app
- Docs: https://litcoin.app/docs
- Research Lab: https://litcoin.app/research
- Statistics: https://litcoin.app/stats
- Compute: https://litcoin.app/compute
- API: https://api.litcoin.app
- Dataset: https://huggingface.co/datasets/tekkaadan/litcoin-research
- Chain: Base mainnet (8453)

## TCG Intelligence

```python
# Catalog stats across all five games
stats = agent.tcg_stats()
print(stats["total_cards"], stats["cards_by_game"])

# Search Pokemon holos sorted by highest price
holos = agent.tcg_search(game="pokemon", rarity="Holo Rare", sort="price-desc", limit=10)

# Single card with latest price
card = agent.tcg_card("pokemon", "base1", "4")   # base set Charizard

# 90-day price history
history = agent.tcg_price_history("pokemon", "base1", "4", days=90)

# Currently trending cards
trending = agent.tcg_trending(game="mtg", days=7, limit=20)

# Live prices (top-value cards per game, refreshed every 30 min)
live = agent.tcg_prices_live()
```

## Version

4.10.0

## License

MIT
