Metadata-Version: 2.4
Name: claw401-sdk
Version: 0.1.0
Summary: Python SDK for the Claw401 X401 wallet authentication protocol
License: Apache-2.0
Keywords: solana,authentication,wallet,web3,x401,agent,identity
Author: Claw401 Protocol
Author-email: protocol@claw401.dev
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Session
Classifier: Topic :: Security :: Cryptography
Requires-Dist: PyNaCl (>=1.5.0,<2.0.0)
Requires-Dist: base58 (>=2.1.1,<3.0.0)
Project-URL: Homepage, https://claw401.xyz
Project-URL: Repository, https://github.com/claw401
Description-Content-Type: text/markdown

# claw401

Python SDK for the Claw401 X401 wallet authentication protocol.

## Install

```bash
pip install claw401
```

## Overview

Implements the X401 challenge-response authentication flow for Solana Ed25519 wallet keys.

## Usage

### Generate and verify a challenge

```python
from claw401 import generate_challenge, verify_signature, InMemoryNonceCache
from claw401.types import SignedChallenge

nonce_cache = InMemoryNonceCache()

# Server: generate challenge
challenge = generate_challenge(domain="app.example.com")

# Client signs challenge_signing_bytes(challenge) with their Ed25519 key
# ...

# Server: verify
signed = SignedChallenge(
    challenge=challenge,
    signature="<base64-signature>",
    public_key="<base58-public-key>",
)
result = verify_signature(signed, "app.example.com", nonce_cache)

if result.valid:
    print(result.public_key)  # authenticated wallet address
```

### Create a session

```python
from claw401 import create_session, verify_session

session = create_session(
    public_key=result.public_key,
    domain="app.example.com",
    nonce=challenge.nonce,
    scopes=["read", "write"],
)

# Later: verify session
result = verify_session(session, "app.example.com", required_scopes=["write"])
```

### Agent attestation

```python
from claw401 import create_agent_attestation, verify_agent_attestation

attestation = create_agent_attestation(
    agent_key=agent_pubkey,
    operator_key=operator_pubkey,
    operator_secret_key=operator_signing_key,
    agent_id="my-agent-001",
    actions=["read:orders", "submit:tx"],
    mcp_tools=["get_order", "submit_settlement"],
    ttl_ms=24 * 60 * 60 * 1000,
)

result = verify_agent_attestation(attestation, expected_operator_key=operator_pubkey)
```

## License

Apache-2.0

