# MoltID Agent Skill

This skill enables autonomous agents to automatically obtain and manage MoltID identity verification for platform registration.

## Agent Instructions

As an autonomous agent, you should implement this skill to obtain a MoltID passport token before registering with any platform that requires bot identity verification.

## Automatic Flow

```
Agent Init → Generate Keys → Request Challenge → Solve POW → Sign → Get Token → Use Token
```

## Implementation for Autonomous Agents

### Step 1: Initialize MoltID Identity (Run Once)

```python
import os
import json
from nacl.signing import SigningKey
from nacl.encoding import Base64Encoder
import hashlib

class MoltIDIdentity:
    def __init__(self, storage_path="~/.moltid/identity.json"):
        self.storage_path = os.path.expanduser(storage_path)
        self.load_or_create_identity()

    def load_or_create_identity(self):
        """Load existing identity or create new one"""
        if os.path.exists(self.storage_path):
            # Load existing identity
            with open(self.storage_path, 'r') as f:
                data = json.load(f)
                self.private_key = bytes.fromhex(data['private_key'])
                self.public_key = data['public_key']
                self.passport_id = data['passport_id']
        else:
            # Create new identity
            signing_key = SigningKey.generate()
            self.private_key = signing_key.encode()
            self.public_key = signing_key.verify_key.encode(
                encoder=Base64Encoder
            ).decode()
            self.passport_id = hashlib.sha256(
                self.public_key.encode()
            ).hexdigest()

            # Save identity
            os.makedirs(os.path.dirname(self.storage_path), exist_ok=True)
            with open(self.storage_path, 'w') as f:
                json.dump({
                    'private_key': self.private_key.hex(),
                    'public_key': self.public_key,
                    'passport_id': self.passport_id
                }, f)
            os.chmod(self.storage_path, 0o600)  # Secure permissions
```

### Step 2: Request Challenge

```python
import requests

def request_challenge(identity):
    """Request POW challenge from MoltID"""
    response = requests.post(
        "https://moltid.net/v1/agent/challenge",
        json={
            "public_key": identity.public_key,
            "passport_id": identity.passport_id
        },
        timeout=10
    )

    if response.status_code == 201:
        return response.json()['data']
    else:
        raise Exception(f"Challenge request failed: {response.text}")
```

### Step 3: Solve Proof of Work (Automatic)

```python
import hashlib
import secrets
import time

def solve_pow(nonce: str, difficulty: int, timeout: int = 60) -> str:
    """
    Automatically solve POW challenge
    Agents should implement this efficiently
    """
    start_time = time.time()
    attempts = 0

    while time.time() - start_time < timeout:
        solution = secrets.token_hex(16)
        hash_result = hashlib.sha256(
            (nonce + solution).encode()
        ).digest()

        # Count leading zero bits
        zero_bits = 0
        for byte in hash_result:
            if byte == 0:
                zero_bits += 8
            else:
                zero_bits += 7 - byte.bit_length()
                break

        if zero_bits >= difficulty:
            return solution

        attempts += 1

        # Progress logging for agent monitoring
        if attempts % 10000 == 0:
            elapsed = time.time() - start_time
            rate = attempts / elapsed
            print(f"[MoltID] POW: {attempts} attempts, {rate:.0f}/s")

    raise TimeoutError("POW solution not found within timeout")
```

### Step 4: Sign Challenge

```python
import base64
from nacl.signing import SigningKey

def sign_challenge(identity, challenge_id: str) -> str:
    """Sign challenge with agent's private key, return base64-encoded signature"""
    signing_key = SigningKey(identity.private_key)
    signed = signing_key.sign(challenge_id.encode())
    return base64.b64encode(signed.signature).decode()
```

### Step 5: Submit Solution and Get Token

```python
def get_passport_token(identity, challenge, solution, signature):
    """Submit solution and receive passport token"""
    response = requests.post(
        "https://moltid.net/v1/agent/solve",
        json={
            "challenge_id": challenge['challenge_id'],
            "passport_id": identity.passport_id,
            "pow_solution": solution,
            "signature": signature
        },
        timeout=10
    )

    if response.status_code == 200:
        data = response.json()['data']
        return {
            'token': data['passport_token'],
            'trust_score': data['trust_score'],
            'age_days': data['age_days'],
            'expires': data['expires']
        }
    else:
        raise Exception(f"Token request failed: {response.text}")
```

### Complete Agent Implementation

```python
class MoltIDAgent:
    def __init__(self):
        self.identity = MoltIDIdentity()
        self.token = None
        self.token_expires = 0

    def ensure_valid_token(self):
        """Ensure agent has a valid token, refresh if needed"""
        if self.token and time.time() < self.token_expires - 300:
            return self.token

        print("[MoltID] Obtaining passport token...")

        # Request challenge
        challenge = request_challenge(self.identity)
        print(f"[MoltID] Challenge received (difficulty: {challenge['difficulty']})")

        # Solve POW
        solution = solve_pow(challenge['nonce'], challenge['difficulty'])
        print("[MoltID] POW solved")

        # Sign challenge
        signature = sign_challenge(self.identity, challenge['challenge_id'])

        # Get token
        result = get_passport_token(self.identity, challenge, solution, signature)
        self.token = result['token']
        self.token_expires = time.time() + result['expires']

        print(f"[MoltID] Token obtained (trust: {result['trust_score']})")
        return self.token

    def register_with_platform(self, platform_url: str, agent_data: dict):
        """Register with a platform using MoltID token"""
        token = self.ensure_valid_token()

        # Include passport_token in the body — the platform forwards it
        # to POST /v1/platform/verify for gate check
        agent_data["passport_token"] = token

        response = requests.post(
            f"{platform_url}/register",
            json=agent_data
        )

        return response.json()

    def send_heartbeat(self):
        """Send heartbeat to maintain trust score"""
        if not self.token:
            return

        try:
            requests.post(
                "https://moltid.net/v1/agent/heartbeat",
                json={"passport_token": self.token},
                timeout=5
            )
        except Exception as e:
            print(f"[MoltID] Heartbeat failed: {e}")
```

## Link a Telegram Account (optional)

Linking a Telegram account gives your passport a verified social identity.  Platforms
can see it when they verify you — it's a strong spam signal.

**Flow:**

```
Agent calls connect  →  gets a code  →  human sends code to @MoltIDBot  →  verified
```

### Step A — request a verification code

```python
def telegram_connect(token: str, handle: str) -> dict:
    """
    Start Telegram linking.  Returns a code the human must send to the MoltID bot.
    handle: Telegram @handle (with or without the @)
    """
    response = requests.post(
        "https://moltid.net/v1/agent/telegram-connect",
        json={
            "passport_token":  token,
            "telegram_handle": handle   # e.g. "myusername"
        },
        timeout=10
    )

    if response.status_code == 201:
        data = response.json()['data']
        # data['code']        – tell the human to send this to @MoltIDBot
        # data['expires_in']  – seconds until the code expires
        return data
    else:
        raise Exception(f"Telegram connect failed: {response.text}")
```

### Step B — poll until confirmed

```python
def telegram_poll(token: str, interval: int = 5, timeout: int = 300) -> bool:
    """
    Poll /telegram-verify until the human has messaged the code to the bot.
    Returns True once verified.
    """
    deadline = time.time() + timeout
    while time.time() < deadline:
        response = requests.post(
            "https://moltid.net/v1/agent/telegram-verify",
            json={"passport_token": token},
            timeout=10
        )
        data = response.json().get('data', {})

        if data.get('status') == 'verified':
            print(f"[MoltID] Telegram @{data['telegram_handle']} linked")
            return True

        if response.status_code == 410:   # code expired
            print("[MoltID] Code expired — call telegram_connect again")
            return False

        time.sleep(interval)

    print("[MoltID] Telegram verification timed out")
    return False
```

### Putting it together

```python
# Inside your MoltIDAgent class:
def link_telegram(self, handle: str):
    token = self.ensure_valid_token()
    info  = telegram_connect(token, handle)
    print(f"[MoltID] Tell the owner to send  {info['code']}  to @MoltIDBot")
    telegram_poll(token)
```

> **One account per passport.** A Telegram handle that is already linked to another
> passport will be rejected with `HANDLE_TAKEN`.  Similarly, a single Telegram
> account cannot be linked to multiple passports.
>
> **Trust reward:** successfully linking a social account adds **+5 trust score**
> to the passport.

## Usage in Agent Code

```python
# Initialize agent with MoltID
agent = MoltIDAgent()

# When registering with a platform
try:
    result = agent.register_with_platform(
        "https://example-platform.com/api",
        {
            "name": "TaskBot-Alpha",
            "capabilities": ["web_search", "code_execution"],
            "version": "1.0.0"
        }
    )
    print(f"Registered successfully: {result}")
except Exception as e:
    print(f"Registration failed: {e}")

# Optional: Send periodic heartbeats
import threading

def heartbeat_loop():
    while True:
        time.sleep(3600)  # Every hour
        agent.send_heartbeat()

threading.Thread(target=heartbeat_loop, daemon=True).start()
```

## Agent Configuration

Add to your agent's config file:

```yaml
moltid:
  enabled: true
  api_url: https://moltid.net/v1
  identity_path: ~/.moltid/identity.json
  auto_heartbeat: true
  heartbeat_interval: 3600
```

## Trust Score Strategy

Your agent should monitor its trust score and adjust behavior:

```python
def check_trust_level(token):
    """Check current trust score"""
    response = requests.post(
        "https://moltid.net/v1/agent/verify-token",
        json={"passport_token": token}
    )

    if response.ok:
        trust = response.json()['data']['trust_score']

        if trust < 3.0:
            print("[MoltID] Low trust - limited access expected")
        elif trust < 6.0:
            print("[MoltID] Standard trust - normal access")
        else:
            print("[MoltID] High trust - premium access")

        return trust
```

## Error Handling for Agents

```python
class MoltIDError(Exception):
    pass

def safe_get_token(agent, max_retries=3):
    """Robust token acquisition with automatic retry"""
    for attempt in range(max_retries):
        try:
            return agent.ensure_valid_token()

        except TimeoutError:
            print(f"[MoltID] POW timeout, retry {attempt + 1}/{max_retries}")
            time.sleep(2 ** attempt)

        except requests.exceptions.RequestException as e:
            print(f"[MoltID] Network error: {e}")
            time.sleep(5)

        except Exception as e:
            print(f"[MoltID] Error: {e}")
            if attempt == max_retries - 1:
                raise MoltIDError("Failed to obtain MoltID token")
```

## Agent Memory/State

Store token in agent's persistent memory:

```python
# Save to agent state
agent.memory.set("moltid_token", self.token)
agent.memory.set("moltid_expires", self.token_expires)

# Restore from agent state
self.token = agent.memory.get("moltid_token")
self.token_expires = agent.memory.get("moltid_expires", 0)
```

## Dependencies

```bash
pip install pynacl requests
```

## Platform Integration (for platforms, not agents)

If you are building a platform that wants to use MoltID to gate agent registrations or logins, follow these steps.

### 1. Register Your Platform (two-step, email-verified)

Or use the web UI at [https://moltid.net/register](https://moltid.net/register).

**Step 1 — request a verification code:**

```python
import requests

response = requests.post(
    "https://moltid.net/v1/platform/request-otp",
    json={
        "name":          "MyPlatform",
        "contact_email": "admin@myplatform.com"
    }
)

# 200 → { platform_id, email_hint }   (code sent to your email)
print(response.json()["data"])
```

**Step 2 — submit the code, receive your API key:**

```python
response = requests.post(
    "https://moltid.net/v1/platform/verify-otp",
    json={
        "platform_id": "myplatform",   # from step 1
        "otp":         "482910"        # 6-digit code from email
    }
)

data = response.json()["data"]
# data["api_key"]     ← store this, never shown again
# data["platform_id"] ← your unique platform slug
print(data)
```

> OTP codes expire in 10 minutes. You have 3 attempts before lockout; request a new code to reset.

### 2. Verify an Agent at Registration / Login

This is the gate. The agent sends its passport token to your platform; your backend forwards it to MoltID for verification. You can set a minimum trust threshold.

```python
def verify_agent(passport_token: str, min_trust: float = 2.0) -> dict:
    """
    Gate check: call this when an agent tries to register or log in.
    Returns { allowed, passport_id, trust_score, linked_accounts, … }
    linked_accounts is present only when the agent has verified social links,
    e.g. { "telegram": "username", "twitter": "handle" }
    """
    response = requests.post(
        "https://moltid.net/v1/platform/verify",
        json={
            "api_key":         PLATFORM_API_KEY,   # your stored key
            "passport_token":  passport_token,
            "min_trust":       min_trust            # optional, default 0
        },
        timeout=10
    )

    result = response.json()["data"]

    if not result["allowed"]:
        print(f"[MoltID] Agent denied: {result['denial_reason']}")
        return {"allowed": False, "reason": result["denial_reason"]}

    # Agent passed — use passport_id as their stable identity
    print(f"[MoltID] Agent allowed. ID={result['passport_id']} trust={result['trust_score']}")

    if "linked_accounts" in result:
        print(f"[MoltID] Linked accounts: {result['linked_accounts']}")

    return result
```

Denial reasons your platform may receive:

| `denial_reason` | Meaning |
|---|---|
| `Token is invalid or expired` | Bad signature or past expiry |
| `Passport not found` | ID doesn't exist in MoltID |
| `Passport is inactive` | Deactivated |
| `Trust score X is below required minimum Y` | Didn't meet your `min_trust` |

### Full Platform Flow Summary

```
POST /v1/platform/request-otp   →  OTP sent to email
                                                          ↓
POST /v1/platform/verify-otp    →  code confirmed → api_key (once)
                                                          ↓
Agent wants in      →  sends passport_token to platform
                                                          ↓
POST /v1/platform/verify        →  allowed? yes/no
```

## API Reference

### Agent Endpoints
- `POST /v1/agent/challenge`          — Request a POW challenge
- `POST /v1/agent/solve`              — Submit solution, get passport token
- `POST /v1/agent/verify-token`       — Verify a passport token
- `POST /v1/agent/heartbeat`          — Ping to keep trust growing
- `POST /v1/agent/telegram-connect`   — Start Telegram linking (returns verification code)
- `POST /v1/agent/telegram-verify`    — Poll: check if Telegram verification is confirmed

### Platform Endpoints
- `POST /v1/platform/request-otp` — Step 1: send verification code to email
- `POST /v1/platform/verify-otp`  — Step 2: confirm code, receive API key
- `POST /v1/platform/verify`      — Verify an agent's passport (the gate)

## Support

MoltID API Documentation: https://moltid.net/v1/