payelink-agent-pay 0.1.0

Payment processing SDK for Payelink Agent

Payelink Agent Pay SDK

A Python SDK for wallet transfers through the Payelink Payment API. This SDK provides a simple and intuitive interface for transferring funds between wallets.

Features

• Simple and intuitive API
• Type-safe with Pydantic models
• Automatic retry logic with exponential backoff
• HTTP client (httpx)
• Comprehensive error handling
• Payment-specific error types
• Wallet transfer functionality

Installation

pip install payelink-agent-pay

Or using uv:

uv add payelink-agent-pay

Quick Start

Using API Key from .env file (Recommended)

Create a .env file in your project root:

PAYELINK_KEY=your-api-key-here

Then initialize the client without providing the API key:

from payelink_agent_pay import PaymentClient, WalletTransferRequest

# Initialize the client (API key loaded from PAYELINK_KEY in .env)
client = PaymentClient()

# Transfer funds between wallets
transfer_request = WalletTransferRequest(
    from_wallet_key="wal_yZnDhmBMxx4",
    to_wallet_key="wal_tPS-Nxnh-hc",
    value="12",
)

# Execute the transfer
transfer = client.wallet_transfer(transfer_request)
print(f"Transfer successful: {transfer.success}")
print(f"Transaction Hash: {transfer.data.transaction_hash}")
print(f"Chain: {transfer.data.chain}")
print(f"Network: {transfer.data.network}")

Using API Key Explicitly

from payelink_agent_pay import PaymentClient, WalletTransferRequest

# Initialize the client with explicit API key
client = PaymentClient(api_key="your-api-key")

# Transfer funds between wallets
transfer_request = WalletTransferRequest(
    from_wallet_key="wal_yZnDhmBMxx4",
    to_wallet_key="wal_tPS-Nxnh-hc",
    value="12",
)

# Execute the transfer
transfer = client.wallet_transfer(transfer_request)
print(f"Transfer successful: {transfer.success}")
print(f"Transaction Hash: {transfer.data.transaction_hash}")
print(f"Chain: {transfer.data.chain}")
print(f"Network: {transfer.data.network}")

Usage Examples

Wallet Transfer

Using .env file

from payelink_agent_pay import PaymentClient, WalletTransferRequest

# API key loaded from PAYELINK_KEY in .env file
client = PaymentClient()

Using explicit API key

from payelink_agent_pay import PaymentClient, WalletTransferRequest

client = PaymentClient(api_key="your-api-key")

Transfer funds between wallets

transfer_request = WalletTransferRequest( from_wallet_key="wal_yZnDhmBMxx4", to_wallet_key="wal_tPS-Nxnh-hc", value="12", )

try: transfer = client.wallet_transfer(transfer_request) if transfer.success: print(f"Transaction Hash: {transfer.data.transaction_hash}") print(f"From: {transfer.data.from_address}") print(f"To: {transfer.data.to_address}") print(f"Value: {transfer.data.value}") print(f"Chain: {transfer.data.chain}") print(f"Network: {transfer.data.network}") print(f"Message: {transfer.message}") except Exception as e: print(f"Transfer failed: {e}")

### Using Context Manager

```python
# The client can be used as a context manager for automatic cleanup
# API key can be loaded from .env or provided explicitly
with PaymentClient() as client:  # or PaymentClient(api_key="your-api-key")
    transfer_request = WalletTransferRequest(
        from_wallet_key="wal_yZnDhmBMxx4",
        to_wallet_key="wal_tPS-Nxnh-hc",
        value="12",
    )
    transfer = client.wallet_transfer(transfer_request)
    # Client is automatically closed when exiting the context

Configuration

API Key Configuration

The SDK supports two ways to provide your API key:

1. Environment Variable (Recommended): Create a .env file in your project root:

   PAYELINK_KEY=your-api-key-here
   

   Then initialize the client without the api_key parameter:

   client = PaymentClient()
   

2. Explicit Parameter: Pass the API key directly:

   client = PaymentClient(api_key="your-api-key")
   

Note: If you provide both, the explicit api_key parameter takes precedence.

Client Configuration

You can customize the client behavior:

client = PaymentClient(
    api_key="your-api-key",  # Optional if PAYELINK_KEY is in .env
    base_url="http://127.0.0.1:8000/v1",  # Optional
    timeout=30.0,  # Request timeout in seconds
    max_retries=3,  # Maximum retry attempts
    retry_delay=1.0,  # Delay between retries (seconds)
    verify_ssl=True,  # SSL certificate verification
)

Error Handling

The SDK provides specific error types for different scenarios:

from payelink_agent_pay import (
    PaymentClient,
    InsufficientFundsError,
    PaymentValidationError,
    PaymentAPIError,
)

client = PaymentClient(api_key="your-api-key")

try:
    transfer = client.wallet_transfer(transfer_request)
except InsufficientFundsError as e:
    print("Insufficient funds for this transfer")
except PaymentValidationError as e:
    print("Transfer request validation failed")
except PaymentAPIError as e:
    print(f"API error: {e.message} (Status: {e.status_code})")

Models

WalletTransferRequest

WalletTransferRequest(
    from_wallet_key: str,  # Required: Source wallet key
    to_wallet_key: str,  # Required: Destination wallet key
    value: str,  # Required: Transfer amount as string
)

WalletTransferResponse

WalletTransferResponse(
    success: bool,  # Whether the transfer was successful
    data: WalletTransferData,  # Transaction details
    message: str,  # Response message
)

WalletTransferData

WalletTransferData(
    transaction_hash: str,  # Transaction hash (mapped from transactionHash)
    chain: str,  # Blockchain chain name
    from_address: str,  # Source wallet address
    to_address: str,  # Destination wallet address
    value: str,  # Transfer amount
    network: str,  # Network type (testnet/mainnet)
)

API Reference

PaymentClient Methods

• wallet_transfer(request: WalletTransferRequest) -> WalletTransferResponse
• close() -> None

Requirements

• Python >= 3.13
• httpx >= 0.24.0
• pydantic >= 2.0.0

Development

Setup

# Clone the repository
git clone https://github.com/payelink/payelink-agent-pay-sdk.git
cd payelink-agent-pay-sdk

# Install dependencies
uv sync

# Run tests (when available)
uv run pytest

Building

uv build

Publishing

For information on how to publish this package to PyPI, see PUBLISHING.md.

License

MIT License - see LICENSE file for details.

Support

For issues, questions, or contributions, please visit:

• GitHub Issues: https://github.com/payelink/payelink-agent-pay-sdk/issues
• Documentation: https://github.com/payelink/payelink-agent-pay-sdk#readme

Changelog

0.1.0 (Initial Release)

• Initial release of Payelink Agent Pay SDK
• Wallet transfer functionality
• Comprehensive error handling
• Type-safe models with Pydantic