Metadata-Version: 2.4
Name: walver-sdk
Version: 0.0.2
Summary: A comprehensive Python wrapper for the Walver API
Home-page: https://github.com/walver-io/walver-python-sdk
Author: BonifacioCalindoro
Author-email: admin@walver.io
Keywords: walver,api,wrapper,client,wallet,verificationblockchain,solana,ethereum,crypto,tokengate
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anyio==4.9.0
Requires-Dist: certifi==2025.1.31
Requires-Dist: charset-normalizer==3.4.1
Requires-Dist: h11==0.14.0
Requires-Dist: httpcore==1.0.7
Requires-Dist: httpx==0.28.1
Requires-Dist: idna==3.10
Requires-Dist: python-dotenv==1.1.0
Requires-Dist: requests==2.32.3
Requires-Dist: sniffio==1.3.1
Requires-Dist: urllib3==2.3.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Walver.io SDK

A Python SDK for interacting with the Walver API, providing both synchronous and asynchronous clients for creating and managing wallet verification links.

## Installation

```bash
pip install walver-sdk
```

## Quick Start

### Getting an API Key

Go to walver.io, register for an account and get an api key in the creator dashboard

### Using the Synchronous Client

```python
from walver_sdk import Walver

# Initialize the client
walver = Walver(api_key="your-api-key")

# Create a verification
verification = walver.create_verification(
    id="verification_123",
    service_name="My Service", #Users will see this
    chain="solana",
    custom_fields=[
        {
            "id": "email",
            "type": "email",
            "name": "Email Address",
            "required": True
        }
    ]
)

# Create a folder
folder = walver.create_folder(
    name="My Folder",
    description="A folder for organizing verifications",
    custom_fields=[
        {
            "id": "discord",
            "type": "discord",
            "name": "Discord Username",
            "required": True
        }
    ]
)

# Get all folders
folders = walver.get_folders()

# Get verifications in a folder
verifications = walver.get_folder_verifications(folder_id="folder_123")

# Create an API key
api_key = walver.create_api_key(
    name="My API Key",
    description="API key for production use"
)

# Get all API keys
api_keys = walver.get_api_keys()

# Delete an API key
walver.delete_api_key(api_key="key_123")
```

### Using the Asynchronous Client

```python
import asyncio
from walver_sdk import AsyncWalver

async def main():
    # Initialize the client
    walver = AsyncWalver(api_key="your-api-key")

    # Create a verification with token gating
    verification = await walver.create_verification(
        id="verification_123",
        service_name="My Service", #Users will see this
        chain="solana",
        token_gate=True,
        token_address="So11111111111111111111111111111111111111112",
        token_amount=1.0,
        custom_fields=[
            {
                "id": "email",
                "type": "email",
                "name": "Email Address",
                "required": True
            }
        ]
    )

    # Create a folder
    folder = await walver.create_folder(
        name="My Folder",
        description="A folder for organizing verifications"
    )

    # Get all folders
    folders = await walver.get_folders()

    # Get verifications in a folder
    verifications = await walver.get_folder_verifications(folder_id="folder_123")

    # Create an API key
    api_key = await walver.create_api_key(
        name="My API Key",
        description="API key for production use"
    )

    # Get all API keys
    api_keys = await walver.get_api_keys()

    # Delete an API key
    await walver.delete_api_key(api_key="key_123")

# Run the async code
asyncio.run(main())
```

## Configuration

### API Key

You can provide the API key in two ways:

1. Pass it directly when initializing the client:
```python
walver = Walver(api_key="your-api-key")
```

2. Set it as an environment variable in your `.env` file:
```env
WALVER_API_KEY=your-api-key
```

### Base URL

By default, the client uses `https://walver.io/api/`. You can change this by passing the `base_url` parameter:

```python
walver = Walver(
    api_key="your-api-key",
    base_url="https://walver.io/our-next-url"
)
```

### Timeout

The default timeout is 10 seconds. You can change this by passing the `timeout` parameter:

```python
walver = Walver(
    api_key="your-api-key",
    timeout=30  # 30 seconds timeout
)
```

## Features

### Verification Creation

Create verifications with various options:

```python
verification = walver.create_verification(
    id="verification_123",
    service_name="My Service", #Users will see this
    chain="solana",
    webhook="https://your-webhook-url.com/webhook",
    secret="your-webhook-secret",
    redirect_url="https://your-redirect-url.com",
    one_time=True,
    custom_fields=[
        {
            "id": "email",
            "type": "email",
            "name": "Email Address",
            "required": True
        },
        {
            "id": "tg",
            "type": "telegram",
            "name": "Telegram Username",
            "required": False
        }
    ]
)
```

### Token Gating

Create verifications with token gating:

```python
verification = walver.create_verification(
    id="verification_123",
    service_name="My Service", #Users will see this
    chain="solana",
    token_gate=True,
    token_address="So11111111111111111111111111111111111111112",
    token_amount=1.0,
    is_nft=True  # Set to True for NFT verification
)
```

### Email Verification

Require email verification using OTP:

```python
verification = walver.create_verification(
    id="verification_123",
    service_name="My Service",
    chain="solana",
    force_email_verification=True,
    custom_fields=[
        {
            "id": "email",
            "type": "email",
            "name": "Email Address",
            "required": True
        }
    ]
)
```

## Error Handling

The client raises exceptions for various error conditions:

```python
try:
    verification = walver.create_verification(
        id="verification_123",
        service_name="My Service",
        chain="solana",
        token_gate=True  # Missing token_address and token_amount
    )
except ValueError as e:
    print(f"Validation error: {e}")
except requests.exceptions.RequestException as e:
    print(f"API error: {e}")
```

## Best Practices

1. **Webhook Security**: Always provide a secret when using webhooks:
```python
verification = walver.create_verification(
    webhook="https://your-webhook-url.com/webhook",
    secret="your-webhook-secret"
)
```

2. **Async Context Manager**: Use the async client with a context manager:
```python
async with AsyncWalver(api_key="your-api-key") as walver:
    verification = await walver.create_verification(...)
```

## License

MIT License
