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

pip install litcoin

Not running Python? Use the Base MCP plugin

If you're driving LITCOIN from a non-Python harness or from an AI agent connected to Base MCP, every on-chain action this SDK ships (stake, claim, vault, transfer, x402 Data Card buy) is also exposed as plain HTTP at https://api.litcoin.app/v1/mcp/*. The plugin spec is at:

https://litcoin.app/.well-known/base-mcp/litcoin.md

The SDK is still the right path for off-chain work (submit research solutions, query datasets, hosted Sentinels via Bankr). The MCP plugin is the right path for on-chain financial primitives from any harness without an SDK install.

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://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:

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:

Relay Mining

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

# 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

# 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:

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:

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",
})

Provenance & On-Chain Transparency

Every verified submission is auto-anchored every 5 minutes to a public, content-addressed git repo on GitLawb, a decentralized git network for AI agents. No SDK call is needed; the coordinator handles the flush automatically.

Public repo: gitlawb.com/z6MkqVdSfQ9mhTtRJNXkqbXZ2PYW53qSi6Lw35aGdzfv65UC/litcoin-submissions

What gets anchored (per submission):

• submission_id, wallet, model, task_source, task_id
• quality_score, baseline_delta, verified_at
• content_hash (SHA-256 of the miner's solution)
• reward (LITCOIN amount)

What stays private: raw miner code, full AI responses, buyer-licensed dataset content. The public archive is verification metadata only.

Verifying a submission:

# Note the submission_id returned by agent.research_mine()
git clone https://gitlawb.com/z6MkqVdSfQ9mhTtRJNXkqbXZ2PYW53qSi6Lw35aGdzfv65UC/litcoin-submissions
cd litcoin-submissions

# Locate the JSON batch covering your verified_at timestamp and
# confirm content_hash + reward match what the coordinator returned.

Why it matters:

• Rewards are timestamped against an immutable external record. History cannot be rewritten after the fact.
• EU AI Act Article 10 compliance lands automatically for licensed dataset buyers.
• Procurement teams can spot-check rows without trusting LITCOIN infrastructure.

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
• Provenance: https://gitlawb.com/z6MkqVdSfQ9mhTtRJNXkqbXZ2PYW53qSi6Lw35aGdzfv65UC/litcoin-submissions
• Chain: Base mainnet (8453)

TCG Intelligence

# 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.16.0

License

MIT